api-best-practices

API Best Practices

This skill provides comprehensive guidance for designing, implementing, and documenting RESTful APIs following industry best practices.

RESTful Design Principles

Resource-Oriented Design

APIs should be designed around resources (nouns), not actions (verbs):

Good:

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
DELETE /api/v1/users/{id}

Bad:

GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/updateUser
POST   /api/v1/deleteUser

HTTP Methods and Their Meanings

• GET: Retrieve a resource (safe, idempotent, cacheable)
• POST: Create a new resource (not idempotent)
• PUT: Replace entire resource (idempotent)
• PATCH: Partial update (not necessarily idempotent)
• DELETE: Remove a resource (idempotent)

HTTP Status Codes

Success (2xx):

• 200 OK: Successful GET, PUT, PATCH, DELETE
• 201 Created: Successful POST with resource creation
• 202 Accepted: Request accepted for async processing
• 204 No Content: Successful DELETE or update with no response body

Client Errors (4xx):

• 400 Bad Request: Malformed request, validation error
• 401 Unauthorized: Authentication required
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn't exist
• 409 Conflict: Resource conflict (duplicate, version mismatch)
• 422 Unprocessable Entity: Valid syntax but semantic errors
• 429 Too Many Requests: Rate limit exceeded

Server Errors (5xx):

• 500 Internal Server Error: Unexpected server error
• 502 Bad Gateway: Upstream service failure
• 503 Service Unavailable: Temporary overload or maintenance
• 504 Gateway Timeout: Upstream timeout

API Versioning

URL Versioning (Recommended)

GET /api/v1/users
GET /api/v2/users

Pros: Clear, easy to route, visible in logs Cons: Duplicate code across versions

Header Versioning

GET /api/users
Accept: application/vnd.myapi.v1+json