API Anti-Patterns: How to Avoid Common REST Mistakes

Tomas Vitvar, August 13th, 2010

Comments(5)

Web APIs typically use REST style for communication while moving away from more traditional SOAP web services. Our ProgrammableWeb service directory currently lists around 1500 services which are using REST, and around 360 using SOAP. Why is REST becoming so popular and what are the common mistakes in the REST API design?

Graphic from Open APIs: a State of the Market

REST API, or to be more precise RESTful API implemented with HTTP, inherently adopts Web architecture principles and can take many advantages of already existing Web technology. Your RESTful API does not require any vendor-specific software. Instead, it can run on already available, open, standards-based, and royalty-free technology. Universal linking built on URIs and URLs gives your API the ability to link any resource with any other on the Web. By using Internet media types (previously known as MIME types), your API messages can have different representations such as JSON or XML and serve clients with various needs. And last but not least, layering and separation of concerns together with Web infrastructure intermediaries such as proxies, gateways, and firewalls improve your API’s performance via large-scale, shared caching.

It is not unusual, however, that many APIs that claim to be RESTful actually fail to do so. Mike Pearce gave an interesting talk (slides embedded below) on how you can easily break REST principles and which mistakes you should avoid when designing RESTful API.

Some of the most common mistakes that Mike mentions in his presentation:

• Tunneling everything through GET. You are using HTTP GET method for “writing” while your URIs do not identify a resource but some operation you would like to perform on the resource. HTTP GET has been designed to be idempotent and safe, meaning that no matter how many times you call GET on the same resource, the response should always be the same and no change in application state should occur.
• Ignoring response codes. HTTP protocol has an extensive set of application-level response codes that you can use to describe various results of your API calls. If your API only returns 200 (OK) or 500 (Internal Server Error), or even 200 with an error message encoded in the response body, your application’s loose coupling, reusability and interoperation will be difficult to achieve in changing environments.
• Ignoring caching. It is easy to ignore the caching by including a header “Cache-control: no-cache” in responses of your API calls. HTTP defines a powerful caching mechanism that include ETag, If-Modified-Since header, and 304 Not Modified response code. They allow your clients and servers to negotiate always a fresh copy of the resource and through caching or proxy servers increase you application’s scalability and performance.
• Ignoring hypermedia. If your API calls send representations that do not contain any links, you are most likely breaking the REST principle called Hypermedia as the Engine of Application State (HATEOAS). Hypermedia is the concept of linking resources together allowing applications to move from one state to another by following links. If you ignore hypermedia, it is likely that URIs must be created at the client-side by using some hard-coded knowledge.
• Ignoring MIME types. If resources returned by API calls only have a single representation, you are probably only able to serve a limited number of clients that can understand the representation. If you want to increase a number of clients that can potentially use your API, you should use HTTP’s content negotiation. It allows you to specify standard media types for representations of your resource such as XML, JSON or YAML which in turn increase chances that even unforeseen clients will be able to use your API.

REST style conforms to Web architecture design and, if properly implemented, it allows you to take the full advantage of scalable Web infrastructure. Although you might have reasons for breaking some of REST principles, you should always understand why you are doing so.