Question

What do you need to avoid in setting up a Restful interface to make sure you have not turned it into an RPC?

Answer 1

Do:

• Design your application to be hypertext-driven (Hypermedia as the Engine of Application State – HATEOAS).
• Spend most of your time and effort identifying resources and crafting media types to represent them.
• Think of the entire URI as your resource identifier, and assume it will change in the future.
• Provide all options for continuing further through your application as links in your representation.
• Think of your application as website that will be ‘crawled’ or ‘browsed’ by clients.
• Try writing a client for your API and look for where the coupling occurs.

Don’t:

• Publish URI templates in API documentation. If you must have templates for query parameters for example, make sure they’re part of your media type definition.
• Think of your application as a collection of URIs being acted on by four verbs.
• Serve mime types such as “application/xml” or “application/json” to clients.

To use an analogy, your API should work more like a GPS for your clients and less like a map. You’ll only provide clients with the name of a nearby street. But from then on, they can only do what your application says they can do at any given point.

The purpose of this style is to minimize coupling between your application and its clients. All of the coupling should occur in your media type definition. This simplifies the evolution of the API, and provides a nice mechanism for versioning. It also makes questions about issues such as pagination disappear.

Most “RESTful” APIs don’t follow this pattern. For one that does, see the Sun Cloud API and its backstory.