rest-api-designer

REST API Designer

Design RESTful APIs with proper resource modeling and endpoint structure.

Quick Start

Use resource-based URLs with plural nouns, proper HTTP methods, and consistent patterns.

Instructions

Core REST Principles

Resources, not actions:

Good: GET /users, POST /users
Bad: GET /getUsers, POST /createUser

Use HTTP methods correctly:

• GET: Retrieve (safe, idempotent)
• POST: Create (not idempotent)
• PUT: Replace (idempotent)
• PATCH: Partial update (not idempotent)
• DELETE: Remove (idempotent)

Use plural nouns:

Good: /products, /orders
Bad: /product, /order

Resource Modeling

Identify resources:

1. List main entities (users, products, orders)
2. Identify relationships (user has orders, order has items)
3. Determine hierarchies (posts have comments)

Design URL structure:

/api/v1/resources
/api/v1/resources/{id}
/api/v1/resources/{id}/sub-resources

Example - Blog API:

GET    /api/v1/posts           # List posts
POST   /api/v1/posts           # Create post
GET    /api/v1/posts/{id}      # Get post
PUT    /api/v1/posts/{id}      # Replace post
PATCH  /api/v1/posts/{id}      # Update post
DELETE /api/v1/posts/{id}      # Delete post

GET    /api/v1/posts/{id}/comments    # List comments
POST   /api/v1/posts/{id}/comments    # Create comment

HTTP Methods

GET - Retrieve resources:

GET /api/v1/users           # List all users
GET /api/v1/users/{id}      # Get specific user
GET /api/v1/users?role=admin # Filter users

Response:

{
  "data": [
    { "id": 1, "name": "John" }
  ],
  "meta": {
    "total": 100,
    "page": 1
  }
}

POST - Create resources:

POST /api/v1/users
Content-Type: application/json

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

Response (201 Created):

{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]",
  "created_at": "2024-01-01T00:00:00Z"
}

PUT - Replace resource:

PUT /api/v1/users/{id}
Content-Type: application/json

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