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).

Concept Good Bad

Resource naming /patients , /appointments

/getPatients , /createAppointment

Actions via HTTP methods POST /patients

POST /createPatient

Plural for collections /patients

/patient

Consistent casing kebab-case or camelCase

Mixed styles

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

Method Purpose Idempotent Safe Request Body

GET

Retrieve resource(s) Yes Yes No

POST

Create resource No No Yes

PUT

Replace entire resource Yes No Yes

PATCH

Partial update Yes* No Yes

DELETE

Remove resource Yes No No

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

3. HTTP Status Codes

Success (2xx):

Code Meaning Use When

200 OK

Success GET, PUT, PATCH succeeded

201 Created

Resource created POST succeeded

204 No Content

Success, no body DELETE succeeded

Client Errors (4xx):

Code Meaning Use When

400 Bad Request

Malformed request Invalid JSON, missing required headers

401 Unauthorized

Not authenticated Missing or invalid token

403 Forbidden

Not authorized Valid token, insufficient permissions

404 Not Found

Resource doesn't exist ID not found

409 Conflict

State conflict Duplicate email, version mismatch

422 Unprocessable Entity

Validation failed Business rule violations

429 Too Many Requests

Rate limited Exceeded request quota

Server Errors (5xx):

Code Meaning Use When

500 Internal Server Error

Unexpected error Unhandled exception

503 Service Unavailable

Temporarily down Maintenance, overload

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 }

Approach Pros Cons Best For

Offset Simple, supports jumping to page Slow on large datasets, inconsistent with real-time data Admin panels, reports

Cursor Fast, consistent Can't jump to arbitrary page Infinite scroll, feeds

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):

Code HTTP Status Meaning

VALIDATION_ERROR

422 Input validation failed

NOT_FOUND

404 Resource doesn't exist

UNAUTHORIZED

401 Authentication required

FORBIDDEN

403 Permission denied

CONFLICT

409 State conflict

RATE_LIMITED

429 Too many requests

Pattern 4: Versioning Strategy

URL Versioning (Recommended for ABP):

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

Strategy Example Pros Cons

URL Path /api/v1/

Clear, easy routing Multiple URLs

Header Api-Version: 1

Clean URLs Hidden, harder to test

Query Param ?version=1

Easy testing Can be forgotten

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:

Use Embedding Use Linking

Related data always needed Related data rarely needed

Few relationships Many relationships

Related data is small Related data is large

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

Anti-Pattern Problem Solution

Verb endpoints POST /createPatient

POST /patients

Ignoring HTTP methods Using POST for everything Use appropriate method

No pagination Returning 10,000 items Always paginate

Inconsistent errors Different formats per endpoint Standardize error structure

Exposing internals Database columns in API Design API contract separately

No versioning Breaking changes break clients Version from day one

Deep nesting /a/{id}/b/{id}/c/{id}/d

Flatten, max 2 levels

Integration with Other Skills

Need Skill

AppService implementation abp-service-patterns

Response wrappers api-response-patterns

Input validation fluentvalidation-patterns

Query optimization linq-optimization-patterns

Technical design docs technical-design-patterns

References

• references/rest-best-practices.md

• Detailed REST patterns

• assets/api-design-checklist.md

• Pre-implementation checklist