Design a great API

UX image

Simply providing an Application Programming Interface, aka an API, is not enough to get business done in the digital environment today.

Providing machine readable access to valuable content, data, and algorithms via web technologies are just the beginning of your journey. Leading API providers like Twilio, Stripe, and Slack all provide us with rich examples of how a well run API operation also take healthy design practices, providing robust and current documentation, regular approaches to communications, and other resources to operate an API at scale successfully.

While there are many areas of the modern API life cycle that are impacting how businesses operate and are putting APIs to work, let us take the time to explore a handful of the essentials areas of operating an API these days.

We’ve broken this down into nine areas, to help highlight what is needed for success in the API economy, beyond just the technical of API.

Design

A badly designed API adds to the friction every developer experiences, contributing to a stack of existing concerns associated with developing web and mobile applications.

Following RESTful patterns is more about doing what developers already know, more than it is about religiously following any single philosophy.

Employing existing standards will contribute to interoperability with existing systems and platforms. Thinking through naming, and ordering of endpoints will make an API intuitive for everyone putting it to work.

Getting Started

Making developers look for what they need to get started will drive off even the most seasoned integrators. A mature getting started page for any API providers brings together all of the elements a developer will need to get up and running using an API, including where they should register for an account, register an application and find their API keys, all the way to where they can find documentation in one click.

Don’t assume developers will know where to find things, put it all on a single page, making getting started as frictionless as possible.

Authentication

API developers have become accustomed to four common approaches to authenticating with API resources including Basic Auth, API Keys, OAuth, and JSON Web Tokens — do not reinvent the wheel here. It is important to use existing approaches to securing resources so that developers do not have to learn something new, as well as help ensure there are as many eyes as possible on your approach.

Like getting started, you should be providing a single location where developers can understand what authentication methodologies are employed, and find what they need to get to work integrating.

Documentation

In report after report, documentation is cited as the number one pain point for API developers, resulting in a wealth of API documentation as service providers, as well as very functional, and even attractive looking, open source API documentation solutions.

Having a machine readable API definition for your API using formats like OpenAPI Spec or API Blueprint has become the default for documentation. This enables the auto-generation of interactive API documentation like Swagger UI, as well as more CSS friendly solutions like Redoc.

Code

APIs transcend any single programming language allowing for data, content, and algorithms to be put to use on any platform, but this process still takes code to execute. It is common for API providers to offer a variety of simple samples, more robust code libraries, and when resources are available, full blown SDKs for expediting integration.

Including code in the language of choice of each developer, representing all major programming languages, or even platforms like WordPress and SalesForce, provides a bridge for developers to cross when integrating with APIs.

Communication

Providing a blog with Atom feed for syndication, and operating an active Twitter account has become common place for API operations, often extending and augmenting existing corporate communications, providing an additional, more focused developer strategy.

With many APIs being born out of development and IT groups, one of the most overlooked aspects of operating an API is communication with the community.

With code being the center of conversation much of this communication strategy has also moved to the social coding platform Github, making docs and code more about communication, than just geeking out.

Support

API platforms that don’t provide support do not last long. API developers have grown accustomed to a variety of self-service API support channels, as well as many of the direct support channels like email, chat, phone, and ticket systems. Self-service support like a forum, FAQ, and knowledge bases provide resources that developers can put to work 24/7, while also reducing the time and effort needed to support often large, and time zone diverse communities.

Investment in multiple support channels is a trademark of successful API operations.

Update

Providing an API is all about making a commitment to API consumers. A commitment that you will have to work to keep your business in alignment with. For these commitments to work, many successful API providers offer regular updates regarding platform stability, and as much detail on the roadmap for the platform as possible.

In the API economy a platform’s track record when it comes to stability, and their transparency regarding upcoming changes, will set the tone for the commitment — that is providing an API.

The terms of service guide everything we do online today, and the API economy is no different. There are a handful of legal building blocks that successful API providers employ. This begins with balanced terms of service and continues with a privacy policy protecting the interests of the platform, developers, and end users.

Beyond the TOS and privacy, corporate branding and design guidelines, as well as service level agreements or best practice guidelines should be provided, setting the tone for operations and integration.

Conclusion

These represent nine of the essential areas you should be considering when it comes to the management of your API operations. Simply exposing a machine-readable resource, or set of API resources is not enough today.

It takes a holistic approach, striking the API balance required to make all of this work — keep API provider in sync with their API consumers, and ongoing integration partners.

Hopefully, this helps with some of the essential best practices involved with API operations.