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