Pragmatic RESTful API Design
"REST vs. SOAP" has been an ongoing battle for quite a while, in the tech industry. There is a seemingly upwards trend of the number of open RESTful APIs emerging vs. the SOAP ones. It's probably safe to conclude that, at least among open APIs, REST is winning.
The problem, however is the ambiguity of the answer to the basic question: what is REST?
RESTful API Design
Representational State Transfer (REST) is an architectural style, for distributed hypermedia systems. It was initially defined in 2000 by Roy Fielding in his doctoral dissertation. REST is based on the concept of transfer of representations of resources. A resource is any application entity that can be uniquely addressed with a Uniform Resource Locator (URL). A representation of a resource is a document that captures current or intended state of a resource.
Since REST is an architectural style not: a well-defined specification, it leaves a lot for interpretation. However, with the increased proliferation of the RESTful style in popular web APIs, some common traits have emerged which are now recognized as best-practices in RESTful web API design. REST, in theory, is not limited to the web, but for the purposes of this blog post we assume to be discussing REST in the context of the world-wide web.
Basic Principles
- Proper RESTful APIs extensively utilize HTTP Protocol. Usage of HTTP methods for CRUD, standard HTTP response codes, common HTTP headers and Mime Types is a common practice.
- URLs in RESTful APIs are semantic, resource-centric and have a general structure which looks something like the following:
http://api.example.com/{ver}/{lang}/{resource_type}/{resource_id}.{output_format}?{filters and api_key as arguments}where:
- {ver} indicates the version of the API and allows changing API syntax/behavior without breaking legacy clients (not necessarily providing "new" functionality for them, however). Usually version can be omitted, and it defaults to the latest stable version of the API.
- {lang} in multilingual APIs, is a two-letter ISO abbreviation for a language, e.g. "en" for English, "es" for Spanish etc. Typically defaults to "en" for English, if ommited.
- {resource_type} is the name of the resource, e.g.: user, story, cart, line item etc.
- {resource_id} is a unique identifier of the resource. Can be numeric or alpha-numeric (e.g. in usernames). Often sequence numbers of the internal database schemas are used as identifiers, however usage of universally unique identifiers (UUIDs) leads to better-designed APIs.
- {output_format} - commonly used to let API know which format response is requested in: xml, html, json, bson, rss, atom are some of the common formats implemented. Frequently format can also be indicated using the HTTP Accept-headers.
- {ver} indicates the version of the API and allows changing API syntax/behavior without breaking legacy clients (not necessarily providing "new" functionality for them, however). Usually version can be omitted, and it defaults to the latest stable version of the API.
- Resources in RESTful URLs are often chained. For instance, to access an item in a user's order the resource part of the URL may look like: "user/2323/order/54234/line_item/73321". Important thing to remember about resource chaining is that it represents a hierarchy: the line item belongs to the order and the order belongs to the user.
- Client-server interactions in REST are stateless: in that request must always contain all of the information necessary to understand the request and may not take advantage of the state stored on the server.
- REST encourages caching of requests that can be cached, to minimize network bandwidth utilization. APIs should implicitly or explicitly mark response to a request as cacheable or non-cacheable. If a response is cacheable, then clients are encouraged to locally cache it and reuse data for later, equivalent requests. HTTP headers are typically used to label cacheable content and indicate the permitted duration of cache.
Follow Technorati