What is the API First principle

The API first principle is an extension of contract-first principle. Therefore, a development of an API MUST always start with API design without any upfront coding activities.

API design (e.g., description, schema) is the master of truth, not the API implementation.

API implementation MUST always be compliant to particular API design which represents the contract between API, and it’s consumer.

Effective Web API Design incorporates 3 important elements:

  1. Business Capabilities
  2. Product Thinking
  3. Developer Experience

Business Capabilities

The predominant aims of Web API’s are to digitize the business capabilites that an organisations brings to the market. When embarking on new API or even expanding an existing API, the underlying business capabilities should be well understood and reflected into the API Design.

Far too often developers embark on developing Web API’s with completely the wrong intentions. Web API’s are not specifically for the purpose for enabling some Front End application to get and process data, Web API’s are specifically for any device, platform or partner to integrate with your business and when designing and implementing Web API’s you should be first considering and designing for this capability.

Product Thinking

Applying Product Thinking to the API design process shifts the team focus from a Single Customer or Application, to an effective API design that is able to handle new automation opportunities with little or no customization effort for a given customer segment. This enables a self-service model for workforce, business to business and customer-driven integration.

Developer Experience

The Developer Experience (DX) focuses on a number of aspects of engagement with developers for an API Product. It extends beyond the operational details of the API, to include all aspects of the API product, from first impressions to day-to-day usage and support.

A great DX is vital to the success of an API. When a great DX is delivered, developers quickly and confidentally consume A Web API, which improves market traction of producized API by moving developers from being integrators to becoming experts on the API. This enables them to quickly and efficiently deliver real business value to their organisations.

DX is also vitally important if your API is to be used by internal developers too.

API Design First

The goal of API Design is to make it easier to discover, integrate and deploy solutions in a way that is scalalbe for the organisation and external parties.

Taking API design first approach starts by indentifying the capabilities to deliver then move toward an API design to deliver the desired outcomes - All before writing a line of code.

An API design-first approach has 5 rapidly executed, iterative phases :

  1. Discover - Determine the digital capabilities the API needs to deliver
  2. Design - Produce an initial design or improve on existing API design to address the digital capabilities defined
  3. Prototype - produce a prototype or mmock API to gain feedback
  4. Deliver - Deliver the API through a parallelised effort across developers, QA, Ops and documentation teams.
  5. Onboard - Ensure customers, partners, and/or internal developers are onboard with the API.

The goal of the API first approach is to gather sufficient details to limit the risk of breaking changes in the future. API first and Agile software development practices are ideal companions

Additional Resources