10 Ways to Create APIs Developers Will Love

10 Ways to Create APIs Developers Will Love

by Darryl K. Taft

Approach 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.

Keep 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

Recognize 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.

Never 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

Support 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

Support 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

Consolidate All API Requests Under One API Subdomain

It’s cleaner, easier and more intuitive for developers whom you want to build cool apps using your API. Your API gateway should be the top-level domain.
Example of a good API domain:
http://api.mydomain.com

Mitigate 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).

Complement 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.

Implement 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.