API Design Principles

API Design Principles

Master REST API design principles to build intuitive, scalable, and maintainable APIs. This skill focuses on design theory - for implementation patterns, see abp-api-implementation or abp-service-patterns.

When to Use This Skill

• Designing new REST API contracts
• Reviewing API specifications before implementation
• Establishing API design standards for your team
• Planning API versioning and evolution strategy
• Creating developer-friendly API documentation

Audience

• Backend Architects - API contract design
• Tech Leads - Standards and review
• Business Analysts - Understanding API capabilities

For Implementation: Use abp-service-patterns for AppService code, api-response-patterns for response wrappers, fluentvalidation-patterns for validation.

Core Principles

1. Resource-Oriented Design

APIs expose resources (nouns), not actions (verbs).

Resource Hierarchy:

/api/v1/patients                    # Collection
/api/v1/patients/{id}               # Single resource
/api/v1/patients/{id}/appointments  # Nested collection
/api/v1/appointments/{id}           # Direct access to nested resource

Avoid Deep Nesting (max 2 levels):

# Good - Shallow
GET /api/v1/patients/{id}/appointments
GET /api/v1/appointments/{id}

# Bad - Too deep
GET /api/v1/clinics/{id}/doctors/{id}/patients/{id}/appointments/{id}

2. HTTP Methods Semantics

Idempotent: Multiple identical requests produce same result. Safe: Does not modify server state.

3. HTTP Status Codes

Success (2xx):

Client Errors (4xx):

Server Errors (5xx):

Design Patterns

Pattern 1: Pagination

Always paginate collections - Never return unbounded lists.

Offset-Based (simple, good for small datasets):

GET /api/v1/patients?page=2&pageSize=20

Response:
{
  "items": [...],
  "totalCount": 150,
  "pageNumber": 2,
  "pageSize": 20,
  "totalPages": 8
}

Cursor-Based (efficient for large datasets, real-time data):

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

Response:
{
  "items": [...],
  "nextCursor": "eyJpZCI6MTQzfQ",
  "hasMore": true
}

Pattern 2: Filtering and Sorting

Query Parameters for Filtering:

GET /api/v1/patients?status=active
GET /api/v1/patients?status=active&createdAfter=2025-01-01
GET /api/v1/patients?doctorId=abc-123

Sorting:

GET /api/v1/patients?sorting=name
GET /api/v1/patients?sorting=createdAt desc
GET /api/v1/patients?sorting=lastName,firstName

Searching:

GET /api/v1/patients?filter=john
GET /api/v1/patients?search=john doe

Design Decisions:

• Use WhereIf pattern - only apply filter if parameter provided
• Define allowed sort fields (security - don't expose internal fields)
• Set maximum page size (prevent abuse)

Pattern 3: Error Response Design

Consistent Structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more validation errors occurred.",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format."
      },
      {
        "field": "dateOfBirth",
        "message": "Date of birth cannot be in the future."
      }
    ],
    "traceId": "00-abc123-def456-00"
  }
}

Error Codes (for client handling):

Pattern 4: Versioning Strategy

URL Versioning (Recommended for ABP):

/api/v1/patients
/api/v2/patients

Versioning Policy:

• Major version for breaking changes
• Support N-1 version minimum
• Deprecation notice 6+ months before removal
• Document migration path

Pattern 5: Resource Relationships

Embedding vs Linking:

// Embedded (fewer requests, larger payload)
{
  "id": "patient-123",
  "name": "John Doe",
  "doctor": {
    "id": "doctor-456",
    "name": "Dr. Smith"
  }
}

// Linked (smaller payload, more requests)
{
  "id": "patient-123",
  "name": "John Doe",
  "doctorId": "doctor-456"
}

// Hybrid (with expand parameter)
GET /api/v1/patients/123?expand=doctor,appointments

Decision Criteria:

API Contract Checklist

Resource Design

• Resources are nouns, not verbs
• Plural names for collections
• Consistent naming convention
• Max 2 levels of nesting
• All CRUD mapped to correct HTTP methods

Request/Response

• All collections paginated
• Default and max page size defined
• Filter parameters documented
• Sorting parameters documented
• Consistent error response format

Security

• Authentication method defined
• Authorization on all mutating endpoints
• Rate limiting configured
• Sensitive data not in URLs
• CORS configured

Documentation

• OpenAPI/Swagger spec
• All endpoints documented
• Request/response examples
• Error responses documented

Anti-Patterns to Avoid

Integration with Other Skills

References

• references/rest-best-practices.md - Detailed REST patterns
• assets/api-design-checklist.md - Pre-implementation checklist