designing-apis

Designing APIs

Principles and patterns for designing clean, consistent, and maintainable APIs.

When to Use This Skill

• Designing new API endpoints
• Reviewing API contracts
• Planning API versioning strategies
• Defining request/response schemas
• Building GraphQL schemas
• Documenting APIs

---

REST API Design Principles

Resource-Oriented Design

APIs should be organized around resources, not actions:

GOOD (Resource-oriented):
GET    /users           → List users
GET    /users/123       → Get user 123
POST   /users           → Create user
PUT    /users/123       → Update user 123
DELETE /users/123       → Delete user 123

BAD (Action-oriented):
POST   /getUsers
POST   /createUser
POST   /updateUser
POST   /deleteUser

HTTP Method Semantics

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

URL Structure Patterns

Collection:     /users
Item:           /users/{id}
Nested:         /users/{id}/posts
Action:         /users/{id}/activate (POST only, for non-CRUD)
Filter:         /users?status=active&role=admin
Pagination:     /users?page=2&limit=20
Sort:           /users?sort=created_at&order=desc

---

Request Design

Path Parameters vs Query Parameters

Use	Path Parameters	Query Parameters
Resource identification	/users/123	-
Required filters	/orgs/456/users	-
Optional filters	-	?status=active
Pagination	-	?page=2&limit=20
Sorting	-	?sort=name&order=asc
Search	-	?q=searchterm

Request Body Patterns

// POST /users - Create
{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "admin"
}

// PATCH /users/123 - Partial update
{
  "name": "Jane Doe"
}

// Bulk operations - POST /users/bulk
{
  "operations": [
    { "action": "create", "data": { "email": "..." } },
    { "action": "update", "id": "123", "data": { "name": "..." } }
  ]
}