6

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

2

5 Answers 5

8

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.

1
  • Thanks for helping to spread the word on REST, accurately and clearly.
    – aehlke
    Aug 3, 2009 at 14:35
4

Take advantage of the underlying protocol where possible. Instead of having verbs in your payload try to use (for example) the HTTP GET, POST, PUT, DELETE methods. Your URI should describe a resource but not what to do with it.

2
  • This has NOTHING to do with REST! It's simply HTTP.
    – aehlke
    Aug 3, 2009 at 14:36
  • I simply provided HTTP as an example (since it's probably the most common protocol in this situation) to reinforce that URI's should be verb-free.
    – Bob Gettys
    Aug 3, 2009 at 17:48
3

Some of the things you want to avoid are:

  • Ignoring caching
  • Tunnelling everything through GET (or alternatively POST)
  • Ignoring MIME types

There's a good article here that talks about some of the REST anti-patterns:

http://www.infoq.com/articles/rest-anti-patterns

2

Kind of a broad question but I'll give it a try. For one, only use the HTTP verbs how the were intended. Don't POST to a URL with a url argument that basically overrides the POST and turns it into a GET or DELETE. This is how SOAP works (everything is a POST).

1
  • This is just correct HTTP usage - doesn't have much to do with REST.
    – aehlke
    Aug 3, 2009 at 14:37
2

This article details some design decisions that differentiate RPC from REST:

http://www.pluralsight.com/community/blogs/tewald/archive/2007/04/28/47067.aspx

@S.Lott: thanks, I honestly thought I'd posted that as answer not a comment. I'm losing my marbles.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.