The bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.
API Documentation
When working on any API task, the first step is to establish and capture the contract. API documentation can be done in two predominant ways:
- through a Postman collection,
- with an OpenAPI spec
It is recommended to create both. They serve different, complementary use cases, and it takes only one command to convert from one to another. Start with creating a Postman collection in v3 format, collection-schema-v3. Postman collections are very human-friendly and offer other capabilities like creating an API mock, monitor, SDK, or spec.
Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.
Good practices for API design
See reference/rest-api-best-practices.md [blocked] for the practices well-documented APIs tend to already follow: resource naming, HTTP method/status-code usage, error response shape, versioning, pagination, filtering, auth, idempotency, and backward compatibility. A spec or collection that already follows these renders documentation with nothing left to fix.
Examples
Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
- anyone can look at them to see how your API behaves,
- they can be used to generate a mock from your collection in a single command.
Workflow
- Establish the contract - refer to best practices. Don't just accept the user's ask - fight for the right API design.
- Choose the instrument - Postman collection / OpenAPI spec - or both. Recommend using both to the user. Start with the Postman collection.
