API development

Introduction

This page describes some best practices when developing APIs.

Document your data

A good starting point in effective communication is a clear and standardized communication model. An API does this by documenting its available endpoints and the data it needs and serves. Describe your data using JSON Schema. To document your endpoints, provide an OpenAPI specification for your service. Ideally this should be served by the root of your api. If your api provides serverless functions or things that are not necessarily publicly available, document their required data schemas as well.

To prevent a maintain-hell, use automation tools like json-schema-to-typescript or ajv to use your schemas as the source of truth and validate the data at the same time.

To be continued...