| name | rest-api-design-http-semantics |
| description | Use this skill when designing, implementing, or reviewing REST endpoints and HTTP interactions between services or clients. |
When designing REST APIs:
-
Follow REST conventions strictly:
- GET: read-only
- POST: create or commands
- PUT: full update
- PATCH: partial update
- DELETE: deletion
-
Use correct HTTP status codes:
- 200, 201, 204 for success
- 400 for validation errors
- 401 for unauthenticated
- 403 for unauthorized
- 404 for missing resources
- 409 for conflicts
-
API structure:
/api/v1/management
- Versioning is mandatory
-
Request/response:
- JSON only
- No envelope unless justified
- Consistent error format
-
Avoid chatty APIs:
- One request = one clear intent
Never expose internal domain models directly.