api-design

name	api-design
description	REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting. Implementation examples in C# ASP.NET Core (primary), Python, and Go.
origin	ECC (customized for C#/.NET stack)

API Design Patterns

Conventions and best practices for designing consistent, developer-friendly REST APIs.

When to Activate

• Designing new API endpoints
• Reviewing existing API contracts
• Adding pagination, filtering, or sorting
• Implementing error handling for APIs
• Planning API versioning strategy
• Building public or partner-facing APIs

Resource Design

URL Structure

# Resources are nouns, plural, lowercase, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sub-resources for relationships
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# Actions that don't map to CRUD (use verbs sparingly)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh

Naming Rules

# GOOD
/api/v1/team-members          # kebab-case for multi-word resources
/api/v1/orders?status=active  # query params for filtering
/api/v1/users/123/orders      # nested resources for ownership

# BAD
/api/v1/getUsers              # verb in URL
/api/v1/user                  # singular (use plural)
/api/v1/team_members          # snake_case in URLs
/api/v1/users/123/getOrders   # verb in nested resource

HTTP Methods and Status Codes

Method Semantics

Method	Idempotent	Safe	Use For
GET	Yes	Yes	Retrieve resources
POST	No	No	Create resources, trigger actions
PUT	Yes	No	Full replacement of a resource
PATCH	No*	No	Partial update of a resource
DELETE	Yes	No	Remove a resource

*PATCH can be made idempotent with proper implementation

Status Code Reference

# Success
200 OK                    — GET, PUT, PATCH (with response body)
201 Created               — POST (include Location header)
204 No Content            — DELETE, PUT (no response body)

# Client Errors
400 Bad Request           — Validation failure, malformed JSON
401 Unauthorized          — Missing or invalid authentication
403 Forbidden             — Authenticated but not authorized
404 Not Found             — Resource doesn't exist
409 Conflict              — Duplicate entry, state conflict
422 Unprocessable Entity  — Semantically invalid (valid JSON, bad data)
429 Too Many Requests     — Rate limit exceeded

# Server Errors
500 Internal Server Error — Unexpected failure (never expose details)
502 Bad Gateway           — Upstream service failed
503 Service Unavailable   — Temporary overload, include Retry-After

Common Mistakes

# BAD: 200 for everything
{ "status": 200, "success": false, "error": "Not found" }

# GOOD: Use HTTP status codes semantically
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }

# BAD: 500 for validation errors
# GOOD: 400 or 422 with field-level details

# BAD: 200 for created resources
# GOOD: 201 with Location header
HTTP/1.1 201 Created
Location: /api/v1/users/abc-123

Response Format

Success Response

{
  "data": {
    "id": "abc-123",
    "email": "[e-mail]",
    "name": "Alice",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Collection Response (with Pagination)

{
  "data": [
    { "id": "abc-123", "name": "Alice" },
    { "id": "def-456", "name": "Bob" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  },
  "links": {
    "self": "/api/v1/users?page=1&per_page=20",
    "next": "/api/v1/users?page=2&per_page=20",
    "last": "/api/v1/users?page=8&per_page=20"
  }
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "invalid_format"
      },
      {
        "field": "age",
        "message": "Must be between 0 and 150",
        "code": "out_of_range"
      }
    ]
  }
}

Pagination

Offset-Based (Simple)

GET /api/v1/users?page=2&per_page=20

SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 20;

Pros: Easy to implement, supports "jump to page N" Cons: Slow on large offsets, inconsistent with concurrent inserts

Cursor-Based (Scalable)

GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20

SELECT * FROM users
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT 21;  -- fetch one extra to determine has_next

{
  "data": [...],
  "meta": {
    "has_next": true,
    "next_cursor": "eyJpZCI6MTQzfQ"
  }
}

Pros: Consistent performance, stable with concurrent inserts Cons: Cannot jump to arbitrary page

When to Use Which

Use Case	Pagination Type
Admin dashboards, small datasets (<10K)	Offset
Infinite scroll, feeds, large datasets	Cursor
Public APIs	Cursor (default) with offset (optional)
Search results	Offset (users expect page numbers)

Filtering, Sorting, and Search

Filtering

# Simple equality
GET /api/v1/orders?status=active&customer_id=abc-123

# Comparison operators (use bracket notation)
GET /api/v1/products?price[gte]=10&price[lte]=100
GET /api/v1/orders?created_at[after]=2025-01-01

# Multiple values (comma-separated)
GET /api/v1/products?category=electronics,clothing

# Nested fields (dot notation)
GET /api/v1/orders?customer.country=US

Sorting

# Single field (prefix - for descending)
GET /api/v1/products?sort=-created_at

# Multiple fields (comma-separated)
GET /api/v1/products?sort=-featured,price,-created_at

Sparse Fieldsets

# Return only specified fields (reduces payload)
GET /api/v1/users?fields=id,name,email

Authentication and Authorization

Token-Based Auth

# Bearer token in Authorization header
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# API key (for server-to-server)
GET /api/v1/data
X-API-Key: sk_live_abc123

Rate Limiting

Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

# When exceeded
HTTP/1.1 429 Too Many Requests
Retry-After: 60

Rate Limit Tiers

Tier	Limit	Window	Use Case
Anonymous	30/min	Per IP	Public endpoints
Authenticated	100/min	Per user	Standard API access
Premium	1000/min	Per API key	Paid API plans
Internal	10000/min	Per service	Service-to-service

Versioning

URL Path Versioning (Recommended)

/api/v1/users
/api/v2/users

Strategy:

1. Start with /api/v1/ — don't version until you need to
2. Maintain at most 2 active versions (current + previous)
3. Non-breaking changes don't need a new version (add fields, add optional params)
4. Breaking changes require a new version (remove/rename fields, change types)

Implementation Patterns

C# — ASP.NET Core Minimal API (Recommended for new .NET projects)

// Program.cs — route group approach
var users = app.MapGroup("/api/v1/users")
    .RequireAuthorization()
    .WithTags("Users");

users.MapPost("/", async (
    CreateUserRequest request,
    IUserService service,
    CancellationToken cancellationToken) =>
{
    if (string.IsNullOrWhiteSpace(request.Email) || !request.Email.Contains('@'))
        return Results.UnprocessableEntity(new
        {
            error = new
            {
                code = "validation_error",
                message = "Request validation failed",
                details = new[] { new { field = "email", message = "Must be a valid email address" } }
            }
        });

    var result = await service.CreateAsync(request, cancellationToken);

    return result.IsSuccess
        ? TypedResults.Created($"/api/v1/users/{result.Value!.Id}", new { data = result.Value })
        : TypedResults.Conflict(new { error = new { code = "email_taken", message = result.Error } });
});

users.MapGet("/{id:guid}", async (
    Guid id,
    IUserService service,
    CancellationToken cancellationToken) =>
{
    var user = await service.FindByIdAsync(id, cancellationToken);
    return user is not null
        ? TypedResults.Ok(new { data = user })
        : TypedResults.NotFound(new { error = new { code = "not_found", message = $"User {id} not found" } });
});

C# — ASP.NET Core Controller (MVC-style, familiar from WPF MVVM patterns)

[ApiController]
[Route("api/v1/[controller]")]
[Authorize]
public sealed class UsersController : ControllerBase
{
    private readonly IUserService _service;

    public UsersController(IUserService service) => _service = service;

    [HttpPost]
    [ProducesResponseType(typeof(ApiResponse<UserDto>), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(ApiError), StatusCodes.Status422UnprocessableEntity)]
    public async Task<IActionResult> CreateAsync(
        [FromBody] CreateUserRequest request,
        CancellationToken cancellationToken)
    {
        var result = await _service.CreateAsync(request, cancellationToken);

        if (!result.IsSuccess)
            return UnprocessableEntity(new { error = new { code = "validation_error", message = result.Error } });

        return CreatedAtAction(
            nameof(GetByIdAsync),
            new { id = result.Value!.Id },
            new { data = result.Value });
    }

    [HttpGet("{id:guid}")]
    [ProducesResponseType(typeof(ApiResponse<UserDto>), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetByIdAsync(Guid id, CancellationToken cancellationToken)
    {
        var user = await _service.FindByIdAsync(id, cancellationToken);
        return user is not null
            ? Ok(new { data = user })
            : NotFound(new { error = new { code = "not_found", message = $"User {id} not found" } });
    }

    [HttpGet]
    public async Task<IActionResult> ListAsync(
        [FromQuery] int page = 1,
        [FromQuery] int perPage = 20,
        [FromQuery] string? status = null,
        CancellationToken cancellationToken = default)
    {
        var (items, total) = await _service.ListAsync(page, perPage, status, cancellationToken);
        return Ok(new
        {
            data = items,
            meta = new { total, page, per_page = perPage, total_pages = (int)Math.Ceiling(total / (double)perPage) }
        });
    }
}

Python (Django REST Framework)

from rest_framework import serializers, viewsets, status
from rest_framework.response import Response

class CreateUserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    name = serializers.CharField(max_length=100)

class UserViewSet(viewsets.ModelViewSet):
    def create(self, request):
        serializer = CreateUserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = UserService.create(**serializer.validated_data)
        return Response(
            {"data": UserSerializer(user).data},
            status=status.HTTP_201_CREATED,
            headers={"Location": f"/api/v1/users/{user.id}"},
        )

Go (net/http)

func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
        return
    }
    user, err := h.service.Create(r.Context(), req)
    if err != nil {
        switch {
        case errors.Is(err, domain.ErrEmailTaken):
            writeError(w, http.StatusConflict, "email_taken", "Email already registered")
        default:
            writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
        }
        return
    }
    w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
    writeJSON(w, http.StatusCreated, map[string]any{"data": user})
}

API Design Checklist

Before shipping a new endpoint:

• Resource URL follows naming conventions (plural, kebab-case, no verbs)
• Correct HTTP method used (GET for reads, POST for creates, etc.)
• Appropriate status codes returned (not 200 for everything)
• Input validated with schema (FluentValidation, DataAnnotations, etc.)
• Error responses follow standard format with codes and messages
• Pagination implemented for list endpoints (cursor or offset)
• Authentication required (or explicitly marked as public)
• Authorization checked (user can only access their own resources)
• Rate limiting configured
• Response does not leak internal details (stack traces, SQL errors)
• Swagger/OpenAPI spec updated ([ProducesResponseType] attributes)