API standards

Resource design, error shape, auth and versioning rules.

Development standardUpdated 21 days ago (29 Sept 2026) by Developer B

Download .md Done editing

Title

Type

How we build in this area: the conventions and decisions the team works to.

Summary

Body

# API standards

## Resource design

- URLs name **nouns**, not verbs: `/skills/:id/assessments`, not
  `/getAssessmentsForSkill`.
- Plural collections, singular members: `GET /skills`, `GET /skills/:id`.
- Nest at most one level deep. Past that, use a query parameter.

## One error shape, everywhere

```json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Level must be between 0 and 4.",
    "field": "level"
  }
}
```

Clients should never have to parse prose to know what went wrong.

## Validation and authorization

- Validate at the boundary, before anything touches the database.
- Every handler answers two questions: *who is this* and *may they do this to
  this specific record*. Ownership checks belong on the server, always.
- Never trust an id from the client to imply permission.

## Pagination

- Cursor-based for anything that grows. Offset pagination drifts as rows are
  inserted.
- Always sort by something unique and stable, such as `(created_at, id)`.

## Versioning

- Additive changes need no version bump. Removing or renaming a field does.
- Version in the path: `/v1/...`.
- Announce a deprecation before you ship the removal.

## Review checklist

- [ ] Ownership and role checks are server-side
- [ ] Input validated at the boundary
- [ ] Errors use the standard shape and the right status code
- [ ] List endpoints paginate with a stable sort
- [ ] No secret, token or personal data in a URL or a log line

Markdown with tables, code blocks and task lists.