api-design

Skill — API Design

This skill defines how to design and review REST APIs on a project using Lytos. An agent loaded with this skill knows the conventions, patterns, and checks required to produce a consistent, production-ready API.

---

When to invoke this skill

• When designing a new API or a new set of endpoints
• When reviewing an existing API for consistency or quality
• When adding endpoints to an existing API — ensure they follow established conventions
• When a team disagrees on URL structure, status codes, or error format

---

Procedure

1. REST conventions

Resources are plural nouns, never verbs. The HTTP method carries the action.

Method	Purpose	Idempotent	Example
GET	Read a resource or collection	Yes	GET /users/42
POST	Create a new resource	No	POST /users
PUT	Full replacement of a resource	Yes	PUT /users/42
PATCH	Partial update of a resource	No	PATCH /users/42
DELETE	Remove a resource	Yes	DELETE /users/42

Nested resources — use them when the child has no meaning without the parent:

GET  /users/{id}/orders            # orders belong to a user
GET  /users/{id}/orders/{orderId}

Flat routes — prefer them when the child is independently addressable or queried across parents:

GET  /orders?user_id=42            # orders can be searched globally
GET  /orders/{orderId}

Rule of thumb: nest at most one level deep. If you reach /a/{id}/b/{id}/c, flatten.

2. URL design

• kebab-case for multi-word segments: /order-items, not /orderItems
• Plural nouns for collections: /users, /products
• No verbs in URLs — use HTTP methods instead
• Query parameters for filtering, sorting, pagination

# ✅ Good
GET /users?role=admin&sort=-created_at&page=2&per_page=20

# ❌ Bad
GET /getAdminUsers

3. HTTP status codes

Code	Name	When to use
200	OK	Successful GET, PUT, PATCH, or DELETE that returns a body
201	Created	Successful POST — include Location header
204	No Content	Successful operation that returns no body
400	Bad Request	Malformed JSON, missing required field, invalid type
401	Unauthorized	No credentials or expired token
403	Forbidden	Valid credentials, but the user lacks permission
404	Not Found	Resource does not exist
409	Conflict	Duplicate creation, version conflict
422	Unprocessable Entity	Valid JSON but fails business rules
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server failure — never intentional