Reading Time: 14 minutes

Your API can be a key to your company’s success as it has been for companies like Twitter, Twilio and Box. Get it wrong and you lose out on a big opportunity.

While at Google, Joshua Block presented in 2006 How to Design a Good API and Why it Matters in the context of one of the most widely used APIs ever created – the Java Core APIs – which may have been used by up to 10 million developers.

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

He cited a two main reasons why API design is important, including:

  1. APIs can be among a company’s greatest assets.
  2. Public APIs are forever – you have one chance to get it right.

Fast-forward nine years later and everything Joshua said holds true, even if the technology and approach for creating APIs is vastly different today. A well-designed API can be a tremendous asset to your company and if adopted by your developer community it can grow your business in ways you might never have anticipated.

Today Twitter’s API handles over 13 billion API calls a day and there are over 750,000 developers around the world contributing applications to the Twitter ecosystem. There are over 9 million applications built on the Facebook Open Graph API. Neither of these companies could have built out the application ecosystems they have today without having great APIs in place.

So how do you design a great API? Is there such a thing? What does it look like?

Keep it simple

Make your API simple and easy to understand. Follow a RESTful approach and model your API after HTTP resources and actions – the same way a browser interacts with the web.

Here is an example of a REST API from a well known subscription billing company.

The API is intuitive and you can tell what it does at a glance.

However, beyond the technical advantages of using REST, modeling your API after real-life things and relationships in your business has a real advantage.

Take the following example.

You can immediately see that this API call returns the address for a specific invoice for a particular account. It’s modeled on real life example. You can imagine a customer on the phone saying “Hi, my account number is 6242525. I have a question. Could you pull up invoice number 345?

Taking this approach means you end up with a common and meaningful language throughout your API that maps to your business and makes it easy for developers to understand.

Another benefit of following RESTful practices is that many API calls can easily be invoked via your browser address bar which makes trying them out relatively simple.

Leverage new standards

Say goodbye to your old friends – XML is out and JSON is in. While many APIs still support XML, many developers are building new APIs to only respond with JSON. Twitter threw its hands up and now only supports JSON after determining that XML usage was significantly low and JSON was more lightweight and developer friendly. Box ditched XML support after learning that it was horrendous at talking about objects and that less than 0.5% of users still wanted to use it.

Protect your loved ones

Use SSL, without any exceptions. It’s easy for hackers to eavesdrop and hijack credentials from users and only supporting HTTPS provides safeguards against this. In addition, when using this approach access tokens can be used instead of requiring users to digitally sign each API request with expensive cryptographic hash functions.

Use OAuth or an open standard for authorization versus creating some custom solution. It will give you more leverage than rolling your own solution that requires every developer needing to figure out how to use it and all its intricacies.

Put your users in control

Giving a user control over how the API operates is a powerful thing. This comes in many ways including the the ability to sort using various rules, searching and filtering. Field filtering is the ability to specify which fields should be returned in the response data. This can be especially useful in cases where there are bandwidth or performance issues, or where a user only cares about a very small subset of the API response data. Another benefit of this is that it limits the need for the API creator to have “different flavors” of the API since it is configurable by the client at runtime.

# field filtering to only return id, sku and customer_id
GET /accounts/6242525/invoices?fields=id,sku,customer_id

# sample response
{
    "invoice_624353": {
        "id": "624353",
        "sku": "AP25626",
        "customer_id": "C241216"
    },
    "invoice_624354": {
        "id": "624354",
        "sku": "AP72533",
        "customer_id": "C917563"
    }
}
 

Show us around

Navigating an API and being able to paginate is especially important when dealing with large sets of data and most SaaS APIs (and many web APIs) fall into this category. Instead of requiring a user to ‘figure out’ where to go next by manually constructing URLs, have your API ‘tell the user’ where to go to get the next page of data. The following is a good example from Facebook’s Open Graph API in which all responses return a ‘paging’ attribute which tells a user where to go to get the previous or next set of data. It’s simple and has the added value that a computer or crawler could use to navigate its way around your API.

{
    "paging": {
        "previous": "https://graph.facebook.com/me/albums?limit=5&before=NITQw",
        "next": "https://graph.facebook.com/me/albums?limit=5&after=MAwDE"
    }
}
 

Don’t break your users

Every API needs to support versioning in order to provide backwards compatibility and a way for users to bind themselves to a specific version if necessary. The easiest way to do this is to implement a version number into a base URI and also support the latest API version under a versionless base URI. This way API client developers can choose to lock themselves into a specific version of the API or always work with the latest one available.

Some companies such as Stripe have taken this even further with date based sub-versions, which account for smaller changes including newly added query parameters, field deprecation, etc. These sub-versions are chosen using a custom HTTP request header.

Beyond versioning, companies need to be careful around changing rules on how their APIs can be used. Changes need to be vetted and carefully communicated. Twitter had to deal with a developer revolt last year after changing how their APIs and content could be used by third-party developers.

Show us how it works

Documentation is key for any developer to be able to adopt and use your API. Your docs should be accessible, easy to find and provide up-to-date details on how they work.

GitHub does a good job of this including documenting parameters and sample responses. Stripe also does a great job – so good in fact that PayPal might have copied them. They cover how authentication works, what error codes mean and even what they consider to be backwards compatibility. This makes it really clear for a client developer to know what to expect from the API.

Takeaway

To summarize, here are some things to consider in designing a great API:

  • Keep it simple and follow REST principles.

  • Give a developer lots of control and flexibility in using your API.

  • Consider how navigation across data and the APIs will work.

  • Support versioning from the very beginning.

  • Keep your API up to date and constantly leverage new standards.

  • Protect your API and keep it secure.

  • Provide great documentation for developers and keep it up to date.

Building a great API can be a key to your company’s success as it has been for many companies so far. Companies like Twilio and DataSift have shown that you can actually build your core business around an API and even make it your primary product.

Creating the perfect API is close to impossible. However it’s clear that companies that look at their APIs as a key part of the business strategy and not just some add-on feature are the ones that will be most successful.



 






Image sources


“APIs cloud”, wikibon.org, http://wikibon.org/blog/cloud-api-standards


“Keep it simple”, MinimalWall, http://www.minimalwall.com/2010/05/10/keep-it-simple-5


“Tour guide”, MyOrpheo, http://myorpheo.com/wp-content/themes/u-design/sliders/cycle/cycle3/images/city_tour_myorpheo.jpg


“The New Standards”, Band, http://www.thenewstandards.com


“People protect what they love”, Uc21Media, http://uc21media.wordpress.com/2012/04/10/architects-leave-architecture-hands-people


“And the winner is”, Thinking Mom’s Revolution, http://thinkingmomsrevolution.com/wp-content/uploads/2012/05/and-the-winner-is-1gmwj15.jpg