api-design

API Design Best Practices

This skill provides comprehensive guidelines for designing clean, consistent, and developer-friendly RESTful APIs.

Resource Naming

URL Structure

Use nouns, not verbs:

✅ Good:
GET    /users
GET    /users/123
POST   /users
PUT    /users/123
DELETE /users/123

❌ Bad:
GET    /getUsers
POST   /createUser
POST   /updateUser/123
POST   /deleteUser/123

Naming Conventions

1. Use plural nouns for collections:

   ✅ /users, /products, /orders
   ❌ /user, /product, /order
   

2. Use lowercase and hyphens for multi-word resources:

   ✅ /user-profiles, /order-items
   ❌ /UserProfiles, /order_items
   

3. Nested resources for relationships:

   ✅ /users/123/orders
   ✅ /posts/456/comments
   ✅ /products/789/reviews
   

4. Limit nesting depth (max 2 levels):

   ✅ /users/123/orders/456
   ❌ /users/123/orders/456/items/789/details
   
   Instead use:
   ✅ /order-items/789
   

HTTP Methods

Standard CRUD Operations

Method	Action	Example	Response
GET	Retrieve	GET /users	200 + list
GET	Retrieve one	GET /users/123	200 + resource
POST	Create	POST /users	201 + resource
PUT	Update (full)	PUT /users/123	200 + resource
PATCH	Update (partial)	PATCH /users/123	200 + resource
DELETE	Delete	DELETE /users/123	204 (no content)

When to Use Each Method

GET - Retrieve data:

GET /users?page=1&limit=10
GET /users/123
GET /users/123/orders

Response: 200 OK
{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]"
}

POST - Create new resource:

POST /users
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "[email protected]"
}

Response: 201 Created
Location: /users/124
{
  "id": 124,
  "name": "Jane Doe",
  "email": "[email protected]",
  "createdAt": "2024-01-06T10:00:00Z"
}

PUT - Replace entire resource:

PUT /users/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "[email protected]",
  "phone": "+1234567890"
}

Response: 200 OK
{
  "id": 123,
  "name": "John Smith",
  "email": "[email protected]",
  "phone": "+1234567890",
  "updatedAt": "2024-01-06T10:00:00Z"
}