2Approach API Design From the ‘Outside-In’ Perspective
Start by asking, what are we trying to achieve with an API? The API’s job is to make the developer as successful as possible. Why? Because the application developer is the lynchpin of the entire API strategy. The primary design principle when crafting your API should be to maximize developer productivity and success.
3Keep Simple Things Simple
The base URL is the most important design affordance of your API. Therefore, a simple, intuitive base URL design makes using your API easy. To keep things simple, use a maximum of two base URLs per resource, keep verbs out of your base URLs, and use HTTP verbs to operate on the collections and elements.
GET /dogs/1234
4Recognize That Good Error Design Is Important
When designing a new API, we might not be thinking about crafting clear error messages, but errors are the primary way that people will learn how your API works. From the perspective of the developer consuming your Web API, everything at the other side of that interface is a black box. Therefore, errors become a key tool in providing context and visibility into how to use an API.
5Never Release an API Without a Version
And make the version mandatory. Versioning is one of the most important considerations when designing your Web API. Specify the version with a “v” prefix, move it to the far left in the URL so that it has the highest scope, and use a simple ordinal number such as v1 or v2, rather than the dot notation like v1.2, which implies a granularity of versioning that doesn’t work with APIs.
Example request to get a dog from a versioned API:
GET /v1/dogs/1234
6Support Partial Response
APIs that use partial response are simple to read and allow the developer to select just the information an app needs at a given time. Partial response also cuts down on bandwidth issues, which is important for mobile apps. You can support partial response by adding optional fields in a comma delimited list.
Example request to get just the name and locations fields for a dog:
GET /v1/dogs/1234?fields=location,name
7Support Multiple Formats
Push things out in more than one format and accept as many formats as necessary. You can usually automate the mapping from format to format. We recommend using JSON (JavaScript Object Notation) as your default format, as it’s the closest thing to universal language. It also has the advantage of being less verbose than XML.
Example request to get just an XML version of a dog:
GET /v1/dogs/1234.json
8Consolidate All API Requests Under One API Subdomain
9Mitigate the ‘Chattiness’ of APIs
API designs that focus on solid resource design are the easiest to learn. However, they are usually “chatty”—meaning that just to build a simple user interface or app, the app will make dozens or hundreds of API calls back to the server. To reduce chattiness and make your API valuable for multiple devices, it’s a good idea to create shortcuts on top of the fundamental resources. Creating a layer of shortcuts is easy once you adhere to the API facade pattern (Tip #10).
10Complement With an SDK
A common question for API providers: Do you need to complement your API with code libraries and software development kits (SDK)? When doing so, you don’t overburden your API design. The SDK can provide the platform-specific code, which developers use in their apps to invoke API operations—meaning you keep your API clean. You might also consider complementing your API with code libraries and SDK because of the simplified integration effort required to work with your API and the reduction of bad or inefficient code.
11Implement the API Facade Pattern
This pattern gives you a buffer or virtual layer between the interface on top and the API implementation on the bottom. You essentially create a facade—a comprehensive view of what the API should be—that is important from the perspective of the app developer and end user of the apps they create.