Contract-first API Development

By Omer Ishag from Laimuna
Jul 22, 2022, 5 min read

Whether you are building website with a backend or creating a microservices app, architecting and implementing server/client APIs reliably with speed can be elusive for a number of reasons.

  • Having separate teams for client and server implementation.
  • Different programming languages for the server and clients.
  • Communication around API can be messy and code changes might not make it to the documentation or at least not on-time.
  • Lack or weak enforcement of style guides

When a new client/server architecture is considered, teams can choose to implement them in either of the following ways:

  • No explicit contract API development
  • Code-first API development
  • Contract-first API development

Each one of those options has it’s pros and cons, but I will focus on contract-first API development and briefly touch on the alternatives when showing the pros and const of contract first API development.

What is contract-first API development?

It’s a development methodology in which the API specification is treated as a first-class citizen in the source code. This means API specification will be the shared single source of truth between both server and clients.

A contract in this context refers to a machine readable standardised API specification. There are number of benefits of having an API contract:

  • Making the API self-service: by generating client codes and documentations
  • Independent client development: By auto generating mock servers from the contract for client implementation
  • Minimal and language-agnostic API specification artifacts

API specifications standards describe how the the server/client interaction should take place, they usually cover things like:

  • HTTP methods (GET, POST, PUT, DELETE)
  • HTTP requests (request body, query and path params)
  • CRUD operations (Ex. queries and mutations for GraphQL)

API specifications standards may or may not describe other information like:

  • Authentication
  • Headers
  • Cookies

Having a contract is extremely valuable to clients developers to understand how to consume the target APIs. When no explicit contract is provided to client development teams, they will have to rely on non-machine readable specification if they exist at all, or dig into the backend codebase.

There are number of machine readable API specifications based on the type of the API. The most common are:

  • OpenAPI: Formerly known as Swagger is a specification for RESTful web services.
  • GraphQL schema language: Schema definition language (SDL) for GraphQL APIs.
  • Protocol Buffers: Interface definition language (IDL) for gRPC services.

Another alternative to contract-first approach is code-first approach. This approach allows you to reap the benefits of having a contract but I would argue it’s less beneficial than contract-first approach since a lot of heavy lifting will still have to be done in server-side code and clients cannot be developed simultaneously with the server.

Benefits of contract-first approach

  • Avoiding development bottlenecks
  • Automatic request validation
  • Lower commitment to server-side frameworks/libraries

Automation and tooling

Contract-first API development makes it possible to take advantage of the automation tools available in the echo system of each API specification standard. OpenAPI, GraphQL and Protobuff all have large echo systems of client and server code generation tools to help with tasks such as client code generation, strong typing, and request validation. This repository shows a minimal example of contract first approach to API development using the following technologies:

  • NestJS
  • NextJs
  • OpenAPI

Further reading:

References