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

{
  "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