Introduction

In the world of software development, there are many different approaches to building applications. One approach I’ve had the pleasure of using is called “schema first development”. This approach emphasizes defining the verbs, routes, request and response structures before diving into writing code. This methodology proves especially beneficial when developing HTTP REST services.

Benefits

Instead of jumping straight into coding, schema first development encourages you to start by creating a formal specification of your API using a standardized format like Open API (formerly known as Swagger). This seemingly small change can have a significant impact on the development process.

Easier Iteration

Think of your OpenAPI document as a living contract for your API. Modifying and refining the schema is significantly faster and less error-prone than making changes to existing code. You can easily experiment with different endpoints, request/response structures, and data models without the burden of building out these aspects in your application. It’s faster to write up your thoughts in JSON/YAML, compared to say Python, Typescript, Golang, etc.

Enhanced Collaboration

OpenAPI provides a common language for developers, product owners, and designers to discuss and understand the API. Everyone can clearly see the intended functionality, data formats, and expected behavior. This shared understanding fosters better communication and reduces the likelihood of misinterpretations. Additionally, its a common language that you can expect other internal and external teams to be able to speak.

Parallel Development

With a well-defined schema in place, your frontend and backend teams can work concurrently. The server team can focus on implementing the API logic according to the specifications, while the client team can build interfaces based on the same contract. This parallel development approach accelerates the overall project timeline. I’ve seen this work exceptionally well when the two sets of developers work on different teams, or even organizations.

Code Generation

There are powerful code generation capabilities that can tie into one’s defined schema. You can automatically generate client libraries (e.g., SDKs) for various programming languages and server-side boilerplate code based on your contract definition. This saves significant time and effort, allowing developers to focus on business logic rather than repetitive coding tasks.

I have not found that I like to use the generated code verbatim, rather, I’m a huge fan of the structs/types being generated for me. As I know they’ll be based on my contract.

Contract Testing

Tools exist that will automatically run tests that validate whether your API adheres to the defined contract. By treating the schema as the “truth”, you can ensure that any changes to the backend implementation do not break the API’s expected behavior. This proactive approach helps prevent regressions and maintain API stability.

Useful Tools

Open API & Swagger Editor

A great online tool to visually design and edit your OpenAPI specifications is Swagger Editor. It provides real-time validation and a helpful interface to visualize your API structure.

As a big fan of Docker, and running software locally, I often will run a local version of the swagger editor. Here’s a sample docker-compose.yaml file that I find useful. This allows you to mount the Open API document you’re writing, and always have it up to date in the web UI:

services:
  swagger-editor:
    image: swaggerapi/swagger-editor
    container_name: swagger-editor
    ports:
      - 8081:8080
    volumes:
      - ./openapi.yaml:/tmp/openapi.yaml
    environment:
      SWAGGER_FILE: /tmp/openapi.yaml

Schemathesis

Schemathesis is a powerful Python library that generates test cases based on your OpenAPI schema. It can be integrated into your CI/CD pipeline to ensure contract compliance as you develop your API.

Conclusion

Schema first development, powered by standards like OpenAPI, promotes a more structured, collaborative, and efficient way of building REST services. By prioritizing the schema, you lay a solid foundation for a robust, maintainable, and scalable application.