In software development projects, especially when separate teams handle frontend and backend systems, coordination can be a major problem. Misunderstandings about data structures, error handling, and other API behaviors can lead to bugs, delays, increased costs, and decreased product quality. These misunderstandings are not minor inconveniences; they can derail a project's timeline and lead to friction between teams.

At Beta Acid, we do a lot of these types of projects and often build REST and GraphQL APIs. Both of these formats can benefit from the principles outlined in this article but we will be specifically discussing tools and processes for REST APIs.

API Contracts Can Help

To address these challenges, API Contracts have become increasingly important. An API Contract is a comprehensive document that outlines the specific behaviors, data structures, and other aspects of each API endpoint of a project. It serves as a single source of truth that both frontend and backend teams can refer to, ensuring that everyone is aligned in their expectations and implementations. The OpenAPI Specification is typically the standard used to create these contracts.

Tools for Creating API Contracts

Manual creation of an API Contract is prone to errors and time-consuming. Various tools have been developed to streamline this process. Swagger Hub is one such tool that has been widely adopted. However, we've recently transitioned to using Stoplight.io for our projects. Stoplight.io offers a graphical user interface that simplifies the creation of API Contracts and minimizes the risk of errors. Although the tool has its limitations and occasional bugs, the overall efficiency gains make it a worthwhile investment.

Leveraging Orval for Frontend Development

At Beta Acid, we've taken our efficiency a step further by using Orval in conjunction with our API Contracts. Orval is a tool that automatically generates the front end networking code (React Query in this case) based on an API Contract. This significantly reduces the workload on frontend developers, allowing them to focus on building out features rather than writing boilerplate code for API calls.

We’ve found this tool to be so useful that we are both sponsors and open source contributors.

By integrating Orval into our workflow, we've been able to:

• Accelerate Development: Frontend developers can immediately start working with auto-generated React Query hooks, speeding up the development process. We’ve found that this can increase delivery time by up to 25%.
• Reduce Errors: Automatically generated code minimizes the risk of human error, leading to more robust applications.
• Maintain Consistency: Using Orval ensures that the frontend code is always in sync with the API Contract, making it easier to manage changes and updates.

A Practical Example: The Swagger Petstore API Contract

To better understand the utility of API Contracts, let's delve into a concrete example using the OpenAPI Specification for the canonical "Swagger Petstore" application. This example will help illustrate how an API Contract serves as a blueprint for both frontend and backend teams.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1

This initial section sets the stage by providing basic information about the API, such as its version and title. It also specifies the base URL where the API can be accessed. This foundational information gives both frontend and backend teams a common starting point.

paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            maximum: 100
            format: int32

Here, the API Contract outlines the available paths and operations. For example, the GET /pets operation is clearly defined, including optional parameters like limiting the number of pets returned. This level of detail ensures that frontend developers know exactly what data they can request, and backend developers know what they need to provide.

responses:
  '200':
    description: A paged array of pets
    headers:
      x-next:
        description: A link to the next page of responses
        schema:
          type: string
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Pets"
  default:
    description: unexpected error
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Error"

This part of the contract specifies what kind of responses to expect. For instance, a successful request to list pets will return a paged array of pets, and may include a link to the next set of pets if pagination is used. This helps both teams understand what the data will look like and how to handle it in their respective systems.

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Finally, the contract defines the structure of the data, specifying what fields are required and what types they should be. This eliminates guesswork and ensures that both teams are aligned in their understanding of the data structures they will be working with.

Extending the Utility of API Contracts with Internal Testing Tools

We’ve taken this a step further by developing an internal testing tool to verify that the APIs we develop match up to the API contract. This Python-based tool leverages the OpenAPI Specification to generate a test plan and execute tests, ensuring that the API behaves as expected.

How It Works

The tool reads the OpenAPI JSON specification from a given URL and generates a structure for all available endpoints. It identifies the allowed methods, parameters, and request bodies for each endpoint. This information is then used to create a test plan that can be executed to validate the API's behavior against the contract. This can then be used as a pre-commit hook in your Github workflow.

Alignment with Beta Acid Principles

The use of an API Contract aligns perfectly with Beta Acid's core principles:

• Always Be Delivering: API Contracts enable parallel development efforts, allowing both frontend and backend teams to work simultaneously toward project completion.
• Be Fast, Keep Focused, Stay Flexible: With a well-defined API Contract, the development process becomes more streamlined, enabling rapid iterations and the flexibility to adapt to changing requirements.
• Communicate Clearly: The API Contract serves as a clear, unambiguous form of communication between the frontend and backend teams, ensuring that everyone is aligned in their understanding of the project's technical aspects.

Summary

Development projects are often presented with the perfect storm: separate backend and frontend teams, building in parallel, on a very tight timeline. Limit your risk, up your communication, and gain efficiency by leveraging API contracts supported by key tools like stoplight.io and Orval to Get Shit Done.

What can we build together?