Key takeaways
- Consistent naming and errors save hours for every consumer
- Version from day one
- Design for AI agents as well as people
An API outlives the team that built it. The partner integrating with it next year will not have anyone to ask, so everything they need has to be in the design and the documentation.
Design
- Resources and actions named the same way everywhere.
- Error responses that are documented and carry a clear code.
- Pagination, filtering and sorting on every list.
- Idempotency keys on anything that creates a record or takes a payment, so a retry on a patchy mobile connection does not create two orders.
Security
- Authentication with scoped tokens.
- Rate limits for each client.
- Audit logs for sensitive operations.
Lifecycle
- A version number from the first release.
- Deprecation notices with enough time to migrate.
- An OpenAPI description kept in step with the code, ideally generated from it.
Ready for AI agents
- A clear description for every endpoint and field, written for a reader with no other context. An agent cannot ask a colleague what "flag_2" means.
- Safe, read only endpoints kept separate from those that change data.
- Consider an MCP server, so assistants can use the API with proper permissions.
Have a question about this guide? Write to us or ask Colony, our AI guide.