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 README.md file. While not a schema per se, it's a good start.
An example of this from my project https://maxslaofmy.systems is below:
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.
Read a short introduction to doing this in practice with AsyncAPI in my DDD book.
Learn more about writing schemas at:
For more on technical documentation writing, two great resources are:
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