Provide an API schema and examples

Do yourself a favor and delegate all usage questions to your API schema and docs.

Having an API schema is the bare minimum acceptance criteria for a system to be used by others. It's common that not having it leads to a lot of questions coming from other teams and stakeholders, filling up your time helping them, instead of building and improving on your solution. While it sounds altruistic to produce a schema and docs "for others", in fact, you win a lot by doing so:

  • Other people know what your thing is, and how it works

  • It moves the design surface into a less technical place, meaning you can work on the API easier and more nimbly

  • It's easier to onboard new team members

The simplest you can go, with basic systems, is to just write down endpoints and some example usage in your file. While not a schema per se, it's a good start.

An example of this from my project is below:


    "name": "amazon-api-gateway"
    "name": "aws-lambda"
    "name": "custom-my-heroku-backend",
    "sla": 97,
    "description": "Just some backend I built on Heroku"
    "name": "amazon-dynamodb"
Status 200


Already this, together with other documentation, gives end-users a useful way to start interacting with your API.

As soon as the API starts becoming complex or it needs to have a portable definition—for example for CI-based linting and validation, document generation, or other machine-readable contexts—then following a standardized convention is something you're absolutely going to want to do. The two major formats today (for the web context, at least) are OpenAPI and AsyncAPI.

The minimum you should aim at providing is:

  • Technical documentation with relevant headings; see an example template here

  • API schema and/or API usage examples (requests, responses)

  • That the above is located somewhere other teams and stakeholders have easy access to the material

Last updated