Apigee, provider of API products and technology for enterprises and developers, has announced the release of "Web API Design: Crafting Interfaces that Developers Love", a free e-book on designing Web APIs. The e-book is a collection of REST API design practices developed in collaboration with various API teams around the world undergoing the Apigee design workshop. The book is written by Brian Mulloy and is an easy read at 38 pages long.
Here's a quick overview of the book. Please read the e-book for the complete details. The e-book talks about the various design decisions and compares how some of the most popular REST API are built today.
Nouns. Use nouns instead of verbs in your base URLs, and keep them simple by using two base URLs per resource. Use HTTP verbs (GET, POST, PUT and DELETE) to operate on collections and elements. Use plural rather than singular nouns. Use concrete rather than abstract names. For example, here's how to get all dogs and a specific dog.
GET /dogs GET /dogs/1
The book discusses options when the client does not support all the different HTTP methods.
Associations. Simplify the associations between resources and avoid deep URL levels. Move complexity like parameters and attributes after the HTTP question mark. Here's how we can get all dogs belonging to particular owner, and just the black ones.
GET /owners/1/dogs GET /owners/1/dogs?color=black
Errors. Use HTTP status codes. The usual suspects include HTTP 200, 400, 401, 403, 404, and 500. Make the messages returned in the payload as verbose as possible. Here's an example JSON payload. Notice the use of URLs for more information.
{
"developerMessage" : "...",
"userMessage" : "...",
"errorCode" : 100,
"moreInfo": "http://developers.company.com/errors/100"
}
The book discusses options when the client always expects a HTTP 200, like some versions of Adobe Flash.
Versions. Make versioning in your API mandatory. Specify the version with a 'v' prefix and put it on the first level. Use a simple ordinal number to emphasize this is an interface and not an implementation. Here's an example of getting all dogs for version 1 of your API.
GET /v1/dogs
Partial Response and Pagination. Use a comma-delimited list to specify what fields you want returned. Use "limit" and "offset" to paginate through resources. These parameters are common and well understood in databases. Here's how to get just the colors and breeds of all the dogs, and the just first 10 dogs.
GET /dogs?fields=color,breed GET /dogs?limit=10&offset=0
Verbs. If your API is sending a response that is not a resource, then it makes better sense to use verbs instead of nouns. Make it clear in your API documentation that these non-resource based APIs are different from the rest of the API. Here's an API call for converting 100 Euros to Chinese Yen.
/convert?from=EUR&to=CNY&amount=100
Content-Types. It's recommended that APIs support different response formats like JSON and XML. To specify what format to return, use the dot type notation. Make JSON the default format, as it is less verbose and can be easily consumed by JavaScript. Here's how to get all dogs in XML.
GET /dogs/1.xml
Attributes. Follow JavaScript conventions for naming attributes. Use CamelCase, the first letter being uppercase or lowercase depending on type of object. Here's an example of a user ID attribute.
{
"userId": 1
}
Search. To do a search across multiple resources, use the verb "search" and the "q" query parameter. Specify the format type using dot type notation. Here's an example of searching for all fluffy resources, in the default and XML formats.
GET /search?q=fluffy GET /search.xml?q=fluffy
To add scope to your search, you can use a resourceful URL with the query parameter. For example, here's searching for all dogs belonging to a particular owner that are fluffy.
GET /owners/1/dogs?q=fluffy
Subdomains. Consolidate all API requests under one API subdomain. Use something like api.company.com. Also create a dedicated developer portal like developers.company.com. You might also want to redirects users who go to the API subdomain in their browsers to the developer portal.
Authentication. Use the standard OAuth 2.0. It allows API access without sharing of passwords. It allows API providers to revoke access tokens. It allows developers to use the same OAuth libraries they use for other APIs.
Chatty APIs. Some API designs become very chatty, which means you need a lot of API calls to the server to build a simple application. The recommendation is to create a complete and RESTful API and provide shortcuts or composite responses if needed.
SDK. It's recommended that API providers complement the API with code samples, libraries and software development kits. It allows for faster adoption on specific platforms. It helps reduce bad or inefficient code that might slow down the service. It helps market the API to different developer communities.
API Facade. There are various ways in architecting your API. The recommended approach is called the "API Facade Pattern", which involves three basic steps.
- Design the ideal API. Design the URLs, parameters, responses, payloads, headers, and so on.
- Implement with stubs. This allows developers to use the API and give feedback even before the API is connected to internal systems.
- Integrate the Facade and the internal systems.
The goal is to make sure that your API is intuitive and easy to use for the app developer.
Download the e-book Web API Design from the Apigee website. For comments and suggestions, visit the API Craft Google Group.