Remote Procedure Calls
REST is often compared to RemoteProcedureCalls, like XmlRpc and RPC-style usages of SOAP (SOAP encoding or DocumentLiteral).
A typical use of RemoteProcedureCalls might be to maintain a jukebox playlist, with methods like "playlist.create" to create a new playlist, "playlist.insert" to insert an item into a playlist, "playlist.delete" to remove an item from the playlist, and "playlist.list" to retrieve the current playlist. One would create this service, for example, to share playlists between work and home. These calls might be defined like:
playlist.create(login, password, listname)
playlist.insert(login, password, listname, songstructure, position)
playlist.remove(login, password, listname, position)
list = playlist.list(login, password, listname)
With this API, your music player could start up and retrieve your playlist (list), add and remove songs in the list order (insert, remove), and of course create new lists (create). songstructure would be a structure that includes song name, album, band, and a URL to the audio, and playlist.list returns an array of those structures.
As time goes on, users may find that they want to add descriptions to their playlists, so the API is extended to support that:
playlist.setDescription(login, password, listname, description)
description = playlist.getDescription(login, password, listname)
Note that you have to make two calls to display a playlist with its description, because we couldn't change playlist.list to also return the description without breaking backward compatibility.
[RogerBenningfield] Please note that this is misleading. If playlist.list() returns a struct (list.items, list.description), multiple calls are in no way required. Multiple calls are often desirable, however, given that they may result in lower bandwidth consumption; one does not always need access to descriptions in order to make use of a playlist.
This API has six actions, which are unique to the management of lists which happen to be song playlists. More actions would be added as more features are added.
[RogerBenningfield] The above is not an artifact of the RPC process. A single playlist.modify() call could be implemented, with all the details contained within an extensible struct. That would usually be considered poor practice by those of an OOP-ish bent, but value aside, it would be trivial to do with an RPC API.
REST works in terms of "resources" (things at URI locations), a small set of uniform actions that are performed on those resources (primarily, but not limited to, HTTP's GET, PUT, POST, and DELETE), and transfering representations of those resources (what gets passed as the content).
The above API for playlists would be implemented in REST as a resource, a list of songs. In HTTP, one would PUT the list to create and update it, GET to retrieve it, and DELETE to remove it. The representation might look like this (abbreviated):
<playlist> <song> <name>Jazzy</name> <uri>http://example.com/jazzy.mp3</uri> </song> <song> <name>Snappy</name> <album>Snappy Tunes</album> <uri>http://example.com/Snappy%20Tunes/snappy.mp3</uri> </song> </playlist>
The same representation can be used with HTTP or a local file system, one can open() the file, read() it, write() a new version, or remove() it. A play list server might store the song lists as records in a database.
Some applications may work directly with the XML. Others may choose to use a library to serialize and deserialize the information. For example, in Python you could use xmltramp, e.g.:
import xmltramp playlist = xmltramp.load('http://example.com/playlist.xml') for song in playlist['song']: print "Name: " + song.name print "URI: " + song.uri
Adding a "description" to the playlist is just a matter of adding it to the representation:
<playlist> <description>Light, Snappy, Jazzy tunes</description> <song> : :
A Perl equivalent to xmltramp is XML::Generator. Sample.
[JonathanSmith AnswerMe] Has anyone coded a Php equivalent?
RPC is REST because it uses HTTP POST, right?
No. HTTP is not REST. HTTP can be used in the REST architectural style. RPCs define their own actions and use HTTP POST only as a "transport" to carry the call.
Can't RPCs be used to implement REST architectural styles?
Technically, yes. A resource's identity is a small, uniform set of actions performed on those resources, and the representation of state of the resources. A resource's identity characterizes REST. You can tell if a service is in the REST Architectural Style (is RESTful) when you can apply virtually all of the same, limited, set of actions on every single resource provided. Compared to the web, one could say such an RPC API would be "like the web but not the web".
Is SOAP RESTful?
There is a profile of SOAP that supports transferring the state of a resource using only the limited actions of HTTP or some other protocols -- that profile is RESTful. Other uses of SOAP carry "actions" to be performed in the SOAP header, regardless of the protocol used -- those would not be RESTful.
This probably doesn't have anything to do with REST; what are SOAP encoding and document-literal?
Correct, REST avoids mandating any particular representation of state. SOAP encoding is an "object graph" developed as a cross-platform representation of programming structures. DocumentLiteral allows any well-formed XML to be carried in a SOAP envelope, and is processed much like XML would be if retrieved without an envelope.
Are CGIs REST?
CommonGatewayInterface (CGI) is an API for standalone programs to respond to web server requests. Just as HTTP is not REST but can be RESTful, so a CGI is not REST but can be RESTful. You can tell if a CGI is RESTful when individual resources are available as seperate URIs. It is the representation of those resources that are passed as content using GET, PUT, POST, etc. (not "parameters to the CGI"), and the same set of small number of actions works across all resources.
Contributors: KenMacLeod, Dotan