REST (REpresentational State Transfer) and RPC (Remote Procedure Call) are two different types of APIs with very different philosophies. Since both types can use HTTP, it can be easy to mix them up, or accidentally build the wrong kind. That said, the differences are actually quite simple.
RPC APIs are about calling procedures remotely. REST APIs are about transferring representations of the state of information. Put another way: RPC focuses on verbs, REST focuses on nouns.
Here are a few ways you can tell these kinds of APIs apart.
RPC APIs often:
- Use POST exclusively
- Require a ‘method’ parameter in the query string (i.e. http://rpcapi.example.com/books?method=list)
- Contain a verb as part of their URLs (i.e. http://rpcapi.example.com/books/1/delete)
- Use one or only very few URLs (i.e. a SOAP WSDL: http://rpcapi.example.com/api.wsdl)
- Only return a “200 OK” response code, and use the document body to describe errors
- Describe metadata about a request or response in the body or query string
REST APIs often:
- Use the full range of HTTP methods (GET, POST, DELETE, etc)
- Only use query strings to alter the scope of information being requested (i.e. for pagination: http://restapi.example.com/books?offset=2)
- Only contain nouns as part of their URLs (i.e. http://restapi.example.com/books/2/author)
- Use a wide array of URLs to identify each piece of information separately
- Use the full spectrum of HTTP response codes http://en.wikipedia.org/wiki/List_of_HTTP_status_codes to describe errors
- Describe metadata about a request or response using HTTP headers where possible
You might notice that the big difference between these two approaches is that REST re-uses a lot of what already exists in the HTTP specification (different methods, ability to communicate errors, identification of resources at unique urls), instead of inventing a new way to do these things within the confines of HTTP.
Both types have their place, but when using HTTP, why not use all of it, and build a REST API?