Introduction to API-First Design

At the start of an organization’s API journey there are a number of questions that need to be answered as a part of the initial planning and analysis phase of the API lifecycle. Among others: why your organization wants to develop and provide an API, who are the stakeholders within the organization, who is the audience for your API? Once a vision is in place for the API, an organization can move into the design phase where the architectural framework for the API is created.

ProgrammableWeb considers API-first design to be the preferred design methodology for designing APIs. With the API-first approach, stakeholders are consulted in an attempt to collaboratively design, mockup, implement and document an API before the application or other channels that will use it even exist. The API-first approach is also something of a clean-room approach whereby the API is designed with little consideration for the existing IT estate. The idea is to design a great API design as though there are no constraints. Then, twist the IT estate into submission, rather than compromise the API’s design.  One major benefit to this approach is that by quickly mocking an API and putting it in front of various stakeholders, an organization can get valuable feedback while continuing to iterate on the design with the goal of providing a service that actually delivers value in the eyes of those stakeholders; the API’s eventual consumers.

Another benefit of designing in this way is that consistency is enforced across interfaces. In today’s multi-screen world, this strategy allows organizations to serve applications across a range of devices be they on the desktop, mobile, tablet or elsewhere.

Traditionally, API design has come after an organization has already released a data-rich application. Akamai Technologies API Evangelist Kirsten Hunter has described the situation where too often, "APIs are created as an afterthought once the product has already been created as a tightly coupled system, with the frontend website and backend system entwined together in a highly codependent way and the REST API having to be ‘shoe-horned’ into this system as a separate entity.”

A number of companies have shown that API-first can work including Lob, Instagram and Etsy. However, this design methodology won't work every time. For example, there are times when the market requires a company move fast to gain a competitive advantage and the time investment to implement API–first design principles may be more than the organization can afford.

In this series, ProgrammableWeb will give you a look at what makes API-first design work including best practices for implementing such a methodology as well as real-world use cases.

Be sure to read the next API Design article: W3C Introduces Three APIs for TV Control, Geolocation, and Web Mentions


Comments (3)

Jason Haygood

Well written Wendell.   Like that alliteration?

I would also add that having a "source of truth", or contract that your internal developers and end consumers can come back to is crucial.  This way, everyone agrees in advance on what should be produced, then after delivery, anyone can go back and verify what was produced is actually what was listed in the contract (i.e. the documentation).

Akamai, whom you mentioned showcases this well here:

They use Apiary's APIFlow software for their API-first design process.



*Full disclosure - I recently started working at Apiary and love our tools!


Thanks Jason! That's a good point about the contract, can you point us to any use cases where this was done. I'd be interested to read about how it performed in action.

Jason Haygood

You bet Wendell - we're actively working on getting more use cases publicized but I couldn't find anything right now that talks to the contract testing aspect.  However, most of our customers love this feature and we'll have multiple use cases to point to in the near future.  

Here's a video from Xero on why they use Apiary and what they love about our tools: