api-design

API Design Standards

Guidelines for designing consistent, intuitive, and maintainable APIs.

REST Principles

Resource-Oriented URLs

# Good: Nouns representing resources
GET    /users
GET    /users/123
POST   /users
PUT    /users/123
DELETE /users/123

# Bad: Verbs/actions in URLs
GET    /getUsers
POST   /createUser
POST   /users/123/delete

Nested Resources

# Child resources under parent
GET    /users/123/posts          # Posts by user 123
GET    /users/123/posts/456      # Specific post
POST   /users/123/posts          # Create post for user

# Avoid deep nesting (max 2 levels)
# Bad: /users/123/posts/456/comments/789/likes
# Good: /comments/789/likes

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Retrieve resource(s)	Yes	Yes
POST	Create new resource	No	No
PUT	Replace entire resource	Yes	No
PATCH	Partial update	Yes	No
DELETE	Remove resource	Yes	No

Method Semantics

// GET - Never modify state
app.get('/users/:id', (req, res) => {
  const user = users.find(req.params.id);
  res.json(user);
});

// POST - Create, return 201 with Location
app.post('/users', (req, res) => {
  const user = users.create(req.body);
  res.status(201)
     .location(`/users/${user.id}`)
     .json(user);
});

// PUT - Full replacement
app.put('/users/:id', (req, res) => {
  const user = users.replace(req.params.id, req.body);
  res.json(user);
});

// PATCH - Partial update
app.patch('/users/:id', (req, res) => {
  const user = users.update(req.params.id, req.body);
  res.json(user);
});

// DELETE - Remove, return 204
app.delete('/users/:id', (req, res) => {
  users.delete(req.params.id);
  res.status(204).send();
});

Status Codes

Success (2xx)

Code	When to Use
200 OK	Successful GET, PUT, PATCH
201 Created	Successful POST that creates resource
204 No Content	Successful DELETE, or update with no body