API Design and Development

3.

Core Principles of API Design

3.1.

Resource-Oriented Design (for RESTful APIs)

3.1.1.

Identifying Resources

3.1.1.1.

Entity Modeling

3.1.1.2.

Resource Relationships

3.1.1.3.

Resource Hierarchies

3.1.2.

URI (Uniform Resource Identifier) Design

3.1.2.1.

Noun-based Naming Conventions

3.1.2.2.

Hierarchical Structure

3.1.2.3.

3.1.2.4.

Clean and Predictable URLs

3.1.2.5.

Avoiding Verbs in URIs

3.1.2.6.

Query Parameters vs. Path Parameters

3.1.3.

Resource Relationships

3.1.3.1.

One-to-Many Relationships

3.1.3.2.

Many-to-Many Relationships

3.1.3.3.

Nested Resources

3.1.3.4.

Resource Linking

3.2.

HTTP Methods (Verbs)

3.2.1.

3.2.1.1.

Safe Operations

3.2.1.2.

Cacheable Responses

3.2.2.

3.2.2.1.

Non-idempotent Operations

3.2.2.2.

Resource Creation

3.2.3.

PUT (Update/Replace)

3.2.3.1.

Idempotent Updates

3.2.3.2.

Complete Resource Replacement

3.2.4.

PATCH (Partial Update)

3.2.4.1.

Partial Resource Updates

3.2.4.2.

Patch Document Formats

3.2.5.

DELETE (Remove)

3.2.5.1.

Resource Deletion

3.2.5.2.

Soft vs. Hard Deletes

3.2.6.

3.2.6.1.

Metadata Retrieval

3.2.6.2.

Resource Existence Checks

3.2.7.

3.2.7.1.

3.2.7.2.

Method Discovery

3.2.8.

Idempotent vs. Safe Methods

3.2.8.1.

Definitions and Examples

3.2.8.2.

Implications for API Consumers

3.2.8.3.

Retry Strategies

3.3.

HTTP Status Codes

3.3.1.

Understanding Code Categories

3.3.1.1.

1xx: Informational

3.3.1.2.

3.3.1.3.

3xx: Redirection

3.3.1.4.

4xx: Client Errors

3.3.1.5.

5xx: Server Errors

3.3.2.

Common Status Codes

3.3.2.1.

3.3.2.2.

3.3.2.3.

3.3.2.4.

3.3.2.5.

301 Moved Permanently

3.3.2.6.

3.3.2.7.

304 Not Modified

3.3.2.8.

400 Bad Request

3.3.2.9.

401 Unauthorized

3.3.2.10.

3.3.2.11.

3.3.2.12.

405 Method Not Allowed

3.3.2.13.

3.3.2.14.

3.3.2.15.

422 Unprocessable Entity

3.3.2.16.

429 Too Many Requests

3.3.2.17.

500 Internal Server Error

3.3.2.18.

502 Bad Gateway

3.3.2.19.

503 Service Unavailable

3.3.2.20.

504 Gateway Timeout

3.3.3.

Custom Status Codes

3.3.3.1.

When to Use Custom Codes

3.3.3.2.

Documentation Requirements

3.4.

Request and Response Design

3.4.1.

Request Headers and Body

3.4.1.1.

Standard Headers

3.4.1.1.1.

3.4.1.1.2.

3.4.1.1.3.

3.4.1.1.4.

3.4.1.2.

3.4.1.2.1.

Naming Conventions

3.4.1.2.2.

Security Considerations

3.4.1.3.

Request Body Structure

3.4.1.3.1.

3.4.1.3.2.

3.4.1.3.3.

3.4.2.

Response Headers and Body

3.4.2.1.

Standard Response Structure

3.4.2.2.

Metadata in Headers

3.4.2.2.1.

3.4.2.2.2.

3.4.2.2.3.

3.4.2.2.4.

3.4.2.3.

Response Body Design

3.4.2.3.1.

Data Envelope Patterns

3.4.2.3.2.

Metadata Inclusion

3.4.3.

Consistent Data Structures

3.4.3.1.

Field Naming Conventions

3.4.3.1.1.

camelCase vs. snake_case

3.4.3.1.2.

Consistency Across Endpoints

3.4.3.2.

Data Types and Formats

3.4.3.2.1.

Date and Time Formats

3.4.3.2.2.

Numeric Precision

3.4.3.2.3.

Boolean Representations

3.4.3.3.

Null Value Handling

3.4.3.3.1.

Omitting vs. Including Null Fields

3.4.3.3.2.

3.4.4.

Designing for Extensibility

3.4.4.1.

Versioning in Payloads

3.4.4.2.

Optional and Required Fields

3.4.4.3.

Schema Evolution Strategies

3.5.

Filtering, Sorting, and Pagination

3.5.1.

Query Parameter Design

3.5.1.1.

Naming Conventions

3.5.1.2.

Supporting Multiple Filters

3.5.1.3.

Logical Operators

3.5.1.3.1.

3.5.1.3.2.

3.5.1.3.3.

3.5.1.4.

Comparison Operators

3.5.1.4.1.

3.5.1.4.2.

3.5.1.4.3.

Pattern Matching

3.5.2.

Pagination Strategies

3.5.2.1.

Offset-based Pagination

3.5.2.1.1.

Limit and Offset Parameters

3.5.2.1.2.

Performance Considerations

3.5.2.2.

Cursor-based (Keyset) Pagination

3.5.2.2.1.

3.5.2.2.2.

Stability Guarantees

3.5.2.3.

Page-based Pagination

3.5.2.3.1.

Page Size Limits

3.5.2.3.2.

Total Count Considerations

3.5.2.4.

Pagination Metadata

3.5.2.4.1.

3.5.2.4.2.

Next/Previous Links

3.5.2.4.3.

Page Information

3.5.3.

Sorting Results

3.5.3.1.

Sort Parameters

3.5.3.1.1.

Single Field Sorting

3.5.3.1.2.

Multi-Field Sorting

3.5.3.2.

3.5.3.2.1.

Ascending vs. Descending

3.5.3.2.2.

Default Sorting

3.5.3.3.

3.5.3.3.1.

Consistent Ordering

3.5.3.3.2.

Tie-Breaking Rules

3.6.

Error Handling and Reporting

3.6.1.

Designing Clear Error Payloads

3.6.1.1.

Error Object Structure

3.6.1.1.1.

3.6.1.1.2.

3.6.1.1.3.

3.6.1.2.

Structured Error Responses

3.6.1.2.1.

RFC 7807 Problem Details

3.6.1.2.2.

Custom Error Formats

3.6.2.

Including Error Codes and Messages

3.6.2.1.

Standardized Error Codes

3.6.2.2.

Human-Readable Messages

3.6.2.3.

Internationalization Considerations

3.6.3.

Validation Errors vs. System Errors

3.6.3.1.

Differentiating Error Types

3.6.3.2.

Providing Contextual Information

3.6.3.3.

Field-Level Validation Errors

3.6.4.

Error Recovery Guidance

3.6.4.1.

Actionable Error Messages

3.6.4.2.

Retry Instructions

3.6.4.3.

Alternative Solutions

Previous

2. API Architectural Styles and Paradigms

Go to top

Next

4. Data Formats and Serialization