Capstone API Contract
Example Contract
Example endpoints:
POST /v1/organizations
GET /v1/organizations/:id
GET /v1/projects?organizationId=org_1&status=active
POST /v1/projects
GET /v1/projects/:id
PATCH /v1/projects/:id
DELETE /v1/projects/:id
GET /v1/projects/:id/tasks
POST /v1/projects/:id/tasks
PATCH /v1/tasks/:id
POST /v1/tasks/:id/comments
Every endpoint must specify authentication, authorization, validation, status codes, response representation, errors, caching behavior, and observability requirements.
For resource state transitions, use hypermedia links where HATEOAS adds meaningful value.
Key Takeaways
- Design the contract before implementing every endpoint.
- Treat tenant boundaries as authorization boundaries.
- Use consistent conventions across all resources.