Conventions
- URLs = nouns, not verbs:
/api/skills, not /api/getSkills.
- HTTP methods for actions: GET, POST, PATCH, DELETE.
- Plural for collections, singular for sub-resources:
/api/skills/42/resources.
- Consistent errors:
{ "error": "validation", "fields": { … } }.
- Paginate with cursors (
?cursor=…&limit=20) or offsets (?page=2).
- Version in URL or header:
/v1/skills, Accept-Version: 1.
Minimal example
GET /v1/skills?roadmap=frontend → 200, list
POST /v1/skills → 201, created
PATCH /v1/skills/42 → 200, updated
DELETE /v1/skills/42 → 204, no content
