REST API Design Best Practices

Resource-Oriented Design

Think in terms of resources, not procedures. Resources are nouns (users, orders, products), not verbs (getUser, createOrder).

Bad: /api/getUser, /api/createOrder, /api/deleteProduct Good: /api/users, /api/orders, /api/products

HTTP Methods & Status Codes

Use standard HTTP methods and status codes: - GET: Retrieve resource - POST: Create resource - PUT/PATCH: Update resource - DELETE: Delete resource

Status codes: - 200: OK - 201: Created - 400: Bad Request - 401: Unauthorized - 404: Not Found - 500: Internal Server Error

Versioning

Plan for evolution. Options: 1. URL versioning: /v1/users, /v2/users 2. Header versioning: Accept: application/vnd.myapi.v1+json 3. Query parameter: /users?version=1

URL versioning is most explicit and easiest for clients.

Pagination

Always paginate list endpoints. Use offset/limit or cursor-based pagination.

Query params: ?page=1&limit=20 or ?cursor=abc123&limit=20

Error Handling

Return meaningful error messages with consistent format:

{ "error": "INVALID_REQUEST", "message": "Email is required", "details": {"field": "email", "reason": "required"} }

Documentation

Write OpenAPI/Swagger specs. Good documentation is critical for API adoption.

Security

• Use HTTPS everywhere
• Implement rate limiting
• Validate & sanitize inputs
• Use OAuth2 for authentication
• Document security requirements

Evolution Strategy

1. Add new endpoints rather than modifying existing ones 2. Support old versions for 2-3 years 3. Deprecate gradually with warning headers 4. Provide migration guides

Testing

• Test happy path and edge cases
• Test error conditions
• Test performance at scale
• Test backward compatibility when upgrading