Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Web API Design Book - Crafting Interfaces that Developers Love

Web API Design Book - Crafting Interfaces that Developers Love

Leia em Português

This item in japanese


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": ""

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.


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 Also create a dedicated developer portal like 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.

  1. Design the ideal API. Design the URLs, parameters, responses, payloads, headers, and so on.
  2. Implement with stubs. This allows developers to use the API and give feedback even before the API is connected to internal systems.
  3. 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.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p