Make APIs a Powerful

Catalyst for Business

Application programming interfaces (APIs) are powerful catalysts to realize business goals faster. They are also a challenge for developers and other stakeholders.

Designing APIs requires thinking about current and future functionality to ensure your applications are flexible, scalable and stepping stones for new products. It means structuring APIs to add features and services later without having to re-architect the entire application.
The ability to connect many APIs together creates capabilities otherwise not possible, which is why Forbes refers to them as billion-dollar opportunities.

Treat developers as your customers

How do you empower developers to use your tools so they help you build an API ecosystem? Treat them as your customers. They are the users most often consuming your APIs.

Well-designed APIs enable developers to easily understand an API’s purpose and functionality so they can quickly become productive. They spare them the need to build applications from the ground up by providing developer kits and sample code, such as examples for connecting with other popular APIs to combine data and features.

API Best Practices

API libraries and frameworks have made it easier for developers to do more, but it comes at a cost. The number of options to build more modular, scalable, and resilient applications has multiplied, ushering in a new age of complexity.

We’ve designed and consulted on several high-profile APIs for data-driven businesses and products, and there are a few key tenets we are dogmatic about.

  1. Make your documentation priority one

Make sure that anyone you want to have access to the documentation can find it easily, and that it can be indexed by search engines like Google and Bing.

Everyone provides reference documentation – the basics of how to make a request and get a response – but

very few providers take that extra step to explain why the API responds the way it does, or what the concepts are that tie different API parts together. Provide insight into why someone might want to use your API to help spark innovation.
  1. Developers are problem solvers

If you give developers who want to work with your API the right tools, you’ll find they will contribute back a thousand fold by finding bugs and working around known issues.

Invest in good error messages and consistent designs so that your users can solve their own problems, rather than waiting on an email response from you. If

you provide a good forum, or even better, respond in a public space like Stack Overflow, your users will help each other.

The best APIs are extensible far beyond what the creator originally imagined, allowing their customers to create entirely new giants upon whose shoulders they now stand.

  1. Make it easy to get started

Developers should quickly understand your API’s main features and how they can start using it. Make the signup process as easy as possible. They should be able to identify

the entry point in 30 seconds, create an account, call the system, and use the results in just a couple of minutes.

  1. Provide a sandbox environment for testing

Let developers test your API by providing a sandbox that simulates all the features without manipulating any actual information. To mimic all the features, include a representative data set or, for bonus points, an anonymized copy of real data. The sandbox provides a temporary
environment that lets developers experiment with your API before moving to production, and the closer to “real” data it is, the easier production launches will be. Postman shareable Collections make this quite easy.
  1. Move fast but don’t break things

There’s nothing worse than reaching the final stretch on your killer product, only to find out that one of the APIs you are building on has released breaking changes that mean you’ll have to rewrite
a significant part of your own product. Likewise, spending an hour debugging an issue in your product that turns out to be an API outage you didn’t know about can wreck productivity.
  1. Communication is key to trust when you are a platform

Provide a roadmap for breaking changes so your partners can prepare for the work it will create for them. Make sure it is easy to register for announcements and
be sure to let your partners know when you’ll be performing updates and routine maintenance.
  1. Version your APIs

On a similar note, provide a logical and easy way to understand the versioning system for your APIs (generally handled in the url, e.g.: “/api/version/endpoint”). This shields your customers from any downtime or disruptions caused by updates and

maintenance to your endpoints by leaving the old ones in place. In addition, it allows your customers more flexibility and options with how they choose to implement your API. Here is an example of Google’s API versioning schedule.

APIs are the basis of all future development

APIs are the cornerstone of all future development. It is essential to get it right. That means designing APIs BEFORE application development.

An API-first approach makes it possible to introduce new features and functions, spin off new products, and more easily synthesize data without changing your application’s basic structure.

It is not always an easy sell when there is intense pressure to be first to market. Resist the temptation to treat APIs as an afterthought. They are the first step in building a thriving developer ecosystem.

APIs unlock digital revenue opportunities

Good API design requires experienced software architects and engineers who understand system architecture, how different components fit together, and design limitations that could affect future development.

For more than a decade our software architects and engineers have designed and built APIs that have enabled our clients to develop data-driven applications that have paid off in sales, retention and savings. Read about this solution for Beeswax Dyson Farming (now Dyson Farming) and our other case studies.

Increase your adoption and usage of your APIs

Experience matters. Let us walk you through the API design process to position you for fast growth.