Best Practices

API Design Principles

Build well-designed, consistent, and developer-friendly APIs using industry best practices and proven design patterns.

REST API Principles

Resource-Based

URLs should represent resources (nouns), not actions (verbs). Use HTTP methods to define operations.

/users
/products/123
✗/getUsers
✗/deleteProduct/123
Stateless

Each request should contain all information needed. Server shouldn't store client state between requests.

Include auth token in each request
Pass all required parameters
Don't rely on session state
Uniform Interface

Use standard HTTP methods, status codes, and conventions consistently across all endpoints.

GET for retrieval
POST for creation
PUT/PATCH for updates
DELETE for removal
Hierarchical

Represent relationships through nested resources and clear hierarchies.

/users/123/posts
/posts/456/comments
/orders/789/items

Resource Naming Conventions

Naming Best Practices

1. Use Plural Nouns for Collections

plaintext

2. Use Lowercase with Hyphens

plaintext

3. Avoid File Extensions

plaintext

4. Use Sub-Resources for Relationships

plaintext

5. Use Query Parameters for Filters

plaintext

HTTP Methods Usage

GETRetrieve Resources

Retrieve data without side effects. Should be safe and idempotent.

http
POSTCreate Resources

Create new resources. Not idempotent - multiple identical requests create multiple resources.

json
PUTReplace Resources

Replace entire resource. Idempotent - same request produces same result.

json
PATCHUpdate Resources

Partially update resource. Only include fields to change. Idempotent.

json
DELETERemove Resources

Delete resources. Idempotent - deleting same resource multiple times has same effect.

json

Idempotency

Understanding Idempotency

An idempotent operation produces the same result when called multiple times with identical parameters. This is crucial for reliable APIs.

Idempotent Methods

GET- Always safe and idempotent
PUT- Replace resource with same data
PATCH- Update same fields to same values
DELETE- Deleting deleted resource returns 404

Non-Idempotent Method

⚠
POST- Creates new resource each time

Making POST Idempotent

Use idempotency keys to prevent duplicate resource creation:

javascript

Endpoint Structure Patterns

Collection and Resource Endpoints
http
Nested Resources
http
Actions on Resources

For operations that don't fit CRUD, use action verbs as sub-resources:

http
Search and Filtering
http
Bulk Operations
json

Response Design

Consistent Response Structure
json
Use Appropriate Status Codes
2xx Success
200 OK - Successful GET, PUT, PATCH, DELETE
201 Created - Successful POST (resource created)
204 No Content - Successful DELETE (no response body)
4xx Client Errors
400 Bad Request - Invalid request data
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
409 Conflict - Resource already exists
422 Unprocessable Entity - Validation failed
429 Too Many Requests - Rate limit exceeded
5xx Server Errors
500 Internal Server Error - Unexpected error
503 Service Unavailable - Temporary downtime
Include Timestamps
json

API Versioning Strategies

1. URL Path Versioning (Recommended)
plaintext
Easy to test and share URLs, works with all HTTP clients
2. Header Versioning
http
⚠Cleaner URLs but harder to test, requires header support
3. Query Parameter Versioning
http
✗Not recommended - mixes versioning with filtering concerns
API Design Best Practices
Use nouns for resources: /users, /products, not /getUsers
Plural collections: /users not /user
Lowercase with hyphens: /user-profiles not /userProfiles
HTTP methods for actions: GET, POST, PUT, PATCH, DELETE
Appropriate status codes: 200, 201, 204, 400, 404, 500
Consistent response structure: Use data/error wrapper objects
Include timestamps: created_at, updated_at in ISO 8601 format
Version your API: Use /v1/, /v2/ in URL path
Support filtering and pagination: Query parameters for search, sort, page
Make operations idempotent: Use idempotency keys for POST requests
Limit nesting depth: Maximum 2 levels (e.g., /users/123/posts/456)
Document your API: Use OpenAPI/Swagger specifications
Previous: Mobile App BackendNext: REST Principles