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:
304 Not Modifiedresponse 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.
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.