API Design Best Practices

Introduction to API Best Practices

In our previous sessions, we explored HTTP fundamentals and RESTful API design principles. Today, we'll focus on best practices that take your APIs from merely functional to truly excellent. These practices help create APIs that are easy to use, maintain, and extend over time.

A well-designed API serves as a contract between your backend services and its consumers (frontend applications, mobile apps, third-party integrations, etc.). Following established best practices ensures this contract is clear, consistent, and durable—qualities that developers using your API will greatly appreciate.

The Restaurant Menu Analogy

A well-designed API is like a well-designed restaurant menu:

• Organized by Category: Just as a menu organizes items by appetizers, main courses, and desserts, an API organizes endpoints by resource type or functional area.
• Clear Descriptions: A good menu describes dishes in detail so customers know what to expect; similarly, good API documentation clearly explains what each endpoint does.
• Consistent Formatting: Menus use consistent formatting for prices, ingredients, and dietary information; APIs should use consistent patterns for request parameters, response formats, and error handling.
• Specials and Recommendations: Menus highlight special dishes or popular combinations; API documentation should highlight common use cases and provide examples.
• Accommodates Special Needs: Menus indicate vegetarian, gluten-free, or allergy-safe options; APIs should provide flexible options for different client needs (pagination, filtering, etc.).
• Evolves Without Confusion: Restaurants update menus while keeping customer favorites; APIs need versioning strategies to evolve while maintaining compatibility.

Just as a poorly designed menu frustrates diners and creates extra work for waitstaff, a poorly designed API frustrates developers and generates support tickets. Both ultimately impact the success of your service.

Naming Conventions and Consistency

Consistency is crucial for creating intuitive, predictable APIs. Developers should be able to guess how your API works based on patterns they've already seen in other parts of your API.

Resource Naming Conventions

• Use plural nouns for collection resources:
  • Good: /users, /products, /categories
  • Avoid: /user, /product, /category
• Use concrete names over abstract concepts:
  • Good: /invoices, /shipments
  • Avoid: /items, /entities (unless genuinely generic)
• Use kebab-case for multi-word resource names:
  • Good: /shipping-addresses, /product-categories
  • Avoid: /shippingAddresses or /shipping_addresses in URIs
• Avoid verbs in URLs (except for non-CRUD operations):
  • Good: POST /orders (create order)
  • Avoid: POST /createOrder
  • Exception for procedures: POST /orders/123/cancel

Parameter Naming Conventions

• Use camelCase for JSON fields:
  • Good: { "firstName": "John", "lastName": "Doe" }
  • Avoid mixing: { "first_name": "John", "lastName": "Doe" }
• Use snake_case for query parameters:
  • Good: /products?sort_by=price&sort_direction=asc
  • Be consistent across all endpoints
• Use consistent parameter names across endpoints:
  • If sort_by is used in one endpoint, don't use order_by in another
  • If limit and offset are used for pagination, use them consistently

Response Formatting Consistency

• Use consistent envelope structure:
  • Example collection response:

    
    {
      "data": [...],
      "pagination": {
        "total": 100,
        "page": 2,
        "limit": 20
      },
      "meta": {
        "request_id": "abc123",
        "response_time": "0.235s"
      }
    }
                    

  • Example single resource response:

    
    {
      "data": {
        "id": 123,
        "name": "Product Name",
        "price": 99.99
      },
      "meta": {
        "request_id": "xyz789",
        "response_time": "0.085s"
      }
    }
                    

• Use consistent date and time formats:
  • Prefer ISO 8601: "created_at": "2023-08-15T14:30:00Z"
  • Document timezone handling (prefer UTC)
• Use consistent number formats:
  • Decide on integer vs. string for IDs and stick with it
  • Use consistent decimal places for monetary values

Error Handling Best Practices

Clear, helpful error responses improve developer experience and reduce support burden. A good error response should:

• Use appropriate HTTP status codes
• Provide a machine-readable error code
• Include a human-readable message
• Add contextual details where helpful
• Follow a consistent structure

Standard Error Response Format

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The request parameter 'email' is invalid",
    "details": {
      "parameter": "email",
      "reason": "Invalid email format",
      "value": "not-an-email"
    },
    "documentation_url": "https://api.example.com/docs/errors#INVALID_PARAMETER"
  }
}
        

Validation Errors

For multiple validation errors, include all issues in a single response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request contains 2 validation errors",
    "validation_errors": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Invalid email format"
      },
      {
        "field": "password",
        "code": "TOO_SHORT",
        "message": "Password must be at least 8 characters"
      }
    ],
    "documentation_url": "https://api.example.com/docs/errors#VALIDATION_FAILED"
  }
}
        

Error Code Hierarchy

Organize error codes hierarchically for better organization and client handling:

// Generic error types
AUTHENTICATION_ERROR   - Problems with authentication
AUTHORIZATION_ERROR    - Problems with permissions
VALIDATION_ERROR       - Problems with request data
RESOURCE_ERROR         - Problems with resources
SYSTEM_ERROR           - Internal system problems

// More specific sub-types
AUTHENTICATION_ERROR.INVALID_CREDENTIALS
AUTHENTICATION_ERROR.TOKEN_EXPIRED
VALIDATION_ERROR.REQUIRED_FIELD
VALIDATION_ERROR.INVALID_FORMAT
RESOURCE_ERROR.NOT_FOUND
RESOURCE_ERROR.ALREADY_EXISTS
        

HTTP Status Code Usage

Use HTTP status codes appropriately and consistently:

Pagination, Filtering, and Sorting

Pagination Best Practices

• Offset-Based Pagination:
  • Use page and limit or offset and limit
  • Include total counts and links to next/previous pages
  • Example: /products?page=2&limit=20
• Cursor-Based Pagination:
  • Better for large datasets and real-time data
  • Use after or before with an opaque cursor
  • Example: /products?limit=20&after=eyJpZCI6MTIzfQ==
• Response Structure:

  
  {
    "data": [...],
    "pagination": {
      "total_items": 547,
      "total_pages": 28,
      "current_page": 2,
      "items_per_page": 20,
      "next_page": "/products?page=3&limit=20",
      "prev_page": "/products?page=1&limit=20"
    }
  }
              

• Default Values:
  • Always provide sensible defaults (e.g., page=1, limit=20)
  • Document these defaults in your API docs
• Maximum Limits:
  • Enforce a reasonable maximum limit to prevent abuse
  • Document this maximum in your API docs

Filtering Best Practices

• Simple Filtering:
  • Use query parameters: /products?category=electronics&in_stock=true
  • Support multiple values: /products?category=electronics,accessories
• Range Filtering:
  • Use min/max prefixes: /products?min_price=100&max_price=500
  • Date ranges: /orders?created_after=2023-01-01&created_before=2023-08-15
• Advanced Filtering:
  • Support operators: /products?price[gt]=100&price[lt]=500
  • Search functionality: /products?search=wireless+headphones
• Filter Negation:
  • Support exclusion: /products?category[not]=apparel
• Document Available Filters:
  • Clearly document which fields can be filtered
  • Document supported operators for each field

Sorting Best Practices

• Basic Sorting:
  • Use sort parameter: /products?sort=price
  • Specify direction: /products?sort=price&order=desc
• Multi-Field Sorting:
  • Comma-separated fields: /products?sort=category,price
  • Direction indicators: /products?sort=category,-price (ascending category, descending price)
• Default Sorting:
  • Document the default sort field and direction
  • Choose sensible defaults (e.g., newest first for time-based resources)
• Limit Sortable Fields:
  • Only allow sorting on indexed fields for performance
  • Document which fields support sorting

API Versioning Strategies

APIs evolve over time, and versioning helps manage changes without breaking existing clients. Several versioning strategies exist, each with pros and cons:

URI Path Versioning

GET /api/v1/products HTTP/1.1
Host: example.com

GET /api/v2/products HTTP/1.1
Host: example.com
        

Pros:

• Very explicit and visible
• Easy to understand
• Works with all clients and tools

Cons:

• Resources exist at multiple URLs
• Violates REST principle that a resource should have one URI
• Clients cannot use different versions for different resources

Query Parameter Versioning

GET /api/products?version=1 HTTP/1.1
Host: example.com

GET /api/products?version=2 HTTP/1.1
Host: example.com
        

Pros:

• Doesn't pollute the URI path
• Still visible and easy to understand
• Works with most clients and tools

Cons:

• Easy to overlook
• May be lost when sharing links
• Caching can be more complex

Header Versioning

GET /api/products HTTP/1.1
Host: example.com
Accept-Version: v1

GET /api/products HTTP/1.1
Host: example.com
Accept-Version: v2
        

Pros:

• Cleaner URIs
• More closely adheres to HTTP's design
• Can mix versions for different resources

Cons:

• Less visible, harder to debug
• Some tools don't support custom headers easily
• Requires more client-side configuration

Content Negotiation Versioning

GET /api/products HTTP/1.1
Host: example.com
Accept: application/vnd.example.v1+json

GET /api/products HTTP/1.1
Host: example.com
Accept: application/vnd.example.v2+json
        

Pros:

• Uses HTTP's built-in content negotiation
• Most REST-compliant approach
• Can request multiple versions and let server choose best match

Cons:

• Most complex to implement
• Hardest for developers to use without specialized tools
• Least visible for debugging

Versioning Best Practices

• Choose one strategy and be consistent:
  • Don't mix versioning strategies within the same API
• Version for breaking changes only:
  • Non-breaking changes (adding fields, endpoints) don't need version changes
• Support multiple versions simultaneously:
  • Give clients time to migrate to new versions
  • Document expected support lifetimes for each version
• Use semantic versioning:
  • Major version changes for breaking changes
  • Minor version changes for new non-breaking features
  • Patch version changes for bug fixes
• Deprecate old versions gracefully:
  • Use deprecation headers to signal upcoming end-of-life
  • Document migration paths to newer versions

API Documentation

High-quality documentation is crucial for API adoption and developer satisfaction. Even the best-designed API will see poor adoption if developers can't easily understand how to use it.

Documentation Components

• Getting Started Guide:
  • Quick introduction to the API
  • Authentication setup
  • Simple examples for common operations
• API Reference:
  • Detailed documentation for all endpoints
  • Request parameters, request body schemas
  • Response formats and status codes
  • Error conditions and handling
• Tutorials and Guides:
  • Walkthroughs for common use cases
  • Integration examples in different languages
  • Authentication flows
• SDK Documentation:
  • If you provide client libraries
  • Language-specific usage examples
• Changelog:
  • Version history
  • Breaking changes
  • New features

OpenAPI (Swagger) Specification

The OpenAPI Specification (formerly Swagger) is a standard format for describing HTTP APIs. It enables:

• Automated documentation generation
• Code generation for clients and servers
• Testing and validation tools
• API discovery and exploration

Example OpenAPI specification snippet:

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
  description: API for managing products, orders, and customers
paths:
  /products:
    get:
      summary: List all products
      parameters:
        - name: category
          in: query
          description: Filter by category
          schema:
            type: string
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A list of products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
          format: float
        # More properties...
        

Interactive Documentation

Interactive API documentation improves the developer experience by allowing:

• Exploring available endpoints
• Testing requests directly from the browser
• Inspecting actual responses
• Trying out different parameters

Tools like Swagger UI, ReDoc, and Postman provide interactive documentation experiences:

Documentation Best Practices

• Keep documentation in sync with the code:
  • Use tools that generate documentation from code annotations
  • Include documentation updates in code review process
• Provide complete request and response examples:
  • Show all required and optional parameters
  • Include headers and status codes
  • Show different response scenarios (success, error)
• Document error conditions:
  • List all possible error codes
  • Explain error causes and how to resolve them
• Include use case examples:
  • Provide examples for common workflows (not just individual endpoints)
  • Show how endpoints work together to accomplish tasks
• Document authentication clearly:
  • Step-by-step guide to obtaining credentials
  • Examples of authenticated requests
  • Security best practices

Authentication and Security

Authentication Methods

Choose the appropriate authentication method based on your security requirements and client types:

API Keys

GET /api/products HTTP/1.1
Host: example.com
X-API-Key: abc123def456
        

Appropriate for:

• Server-to-server API calls
• Public APIs with rate limiting
• Simple integration scenarios

Considerations:

• Simple to implement
• No built-in expiration
• All-or-nothing access (no fine-grained permissions)
• Should be transmitted via headers, not URLs

JSON Web Tokens (JWT)

GET /api/products HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        

Appropriate for:

• Single-page applications (SPAs)
• Mobile applications
• Microservices architectures

Considerations:

• Contains encoded user information and permissions
• Stateless (no server-side storage needed)
• Can't be invalidated before expiration
• Requires careful handling of secret keys

OAuth 2.0

// Client obtains an access token first
POST /oauth/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=abc123&client_id=client123&client_secret=secret456&redirect_uri=https://client.example.org/callback

// Then uses the token for API requests
GET /api/products HTTP/1.1
Host: example.com
Authorization: Bearer access_token_received_from_oauth_server
        

Appropriate for:

• Third-party integrations
• User-delegated access to resources
• Enterprise applications

Considerations:

• Most complex to implement
• Provides sophisticated authorization flows
• Supports scope-based permissions
• Separates authentication from resource access

Security Best Practices

• Always use HTTPS:
  • Never send credentials over unencrypted connections
  • Consider HSTS (HTTP Strict Transport Security)
• Implement rate limiting:
  • Prevent brute force attacks
  • Protect against abuse and DoS
  • Use the 429 Too Many Requests status code
• Use secure token handling:
  • Short expiration times for tokens
  • Secure storage on client side
  • Token revocation capabilities
• Implement proper CORS settings:
  • Restrict to trusted domains
  • Be specific with allowed headers and methods
  • Use the Access-Control-Allow-Credentials header with care
• Validate all input:
  • Sanitize parameters to prevent injection attacks
  • Validate data types, lengths, and formats
  • Use whitelisting over blacklisting
• Follow the principle of least privilege:
  • Provide minimal access necessary for functionality
  • Use fine-grained permissions and scopes

Performance Optimization

Response Time Optimization

• Efficient database queries:
  • Use indexes for frequently filtered fields
  • Optimize joins and complex queries
  • Paginate large result sets
• Asynchronous processing:
  • Use background processing for long-running operations
  • Implement webhooks for notifications
• Server-side caching:
  • Cache expensive database queries
  • Use Redis or similar for distributed caching
  • Invalidate caches appropriately when data changes

Payload Optimization

• Response filtering:
  • Allow clients to request only needed fields
  • Example: /users/123?fields=id,name,email
• Compression:
  • Enable gzip or brotli compression
  • Significantly reduces payload size for text-based responses
• Minimize nested data:
  • Use references instead of embedding large objects
  • Provide separate endpoints for detailed information
• Efficient data formats:
  • Use compact JSON structures
  • Consider binary formats for performance-critical applications

HTTP Caching

Leverage HTTP's built-in caching mechanisms:

• ETag / If-None-Match:
  • Server provides ETag (entity tag) for each response
  • Client includes If-None-Match header with the ETag in subsequent requests
  • Server returns 304 Not Modified if resource hasn't changed
• Last-Modified / If-Modified-Since:
  • Server provides Last-Modified timestamp
  • Client includes If-Modified-Since header in subsequent requests
  • Less precise than ETags but simpler to implement
• Cache-Control headers:
  • Control caching behavior for different resources
  • Example: Cache-Control: max-age=3600, must-revalidate
  • Vary header for content negotiation: Vary: Accept, Accept-Language

Example of implementing ETags and conditional requests:

API Monitoring and Analytics

Key Metrics to Monitor

• Response time:
  • Average, median, 95th percentile, 99th percentile
  • Broken down by endpoint and method
• Error rates:
  • 4xx errors (client errors)
  • 5xx errors (server errors)
  • Trends and spikes
• Request volume:
  • Requests per minute/hour/day
  • Traffic patterns and trends
• Endpoint usage:
  • Most frequently used endpoints
  • Least used endpoints
• Client information:
  • Client types and versions
  • Geographic distribution
• Authentication metrics:
  • Failed authentication attempts
  • Token usage patterns

Implementation Approaches

• Application-level logging:
  • Structured logging of requests, responses, and performance
  • Correlation IDs to track requests across services
• API gateway metrics:
  • Centralized collection of API metrics
  • Rate limiting and quota management
• APM (Application Performance Monitoring):
  • End-to-end transaction tracing
  • Dependency monitoring (databases, external services)
• Synthetic monitoring:
  • Scheduled API tests that simulate client behavior
  • Alerting on failures or performance degradation
• Request tracking:
  • Include request IDs in responses
  • Example: X-Request-ID: 7b44d582-5a88-4136-a307-2f9cap05ef2a
  • Help correlate client issues with server logs

Using Metrics to Improve APIs

• Performance optimization:
  • Identify slow endpoints for optimization
  • Monitor impact of optimizations
• Error resolution:
  • Identify common error patterns
  • Improve validation and error messaging
• Deprecation planning:
  • Identify unused or low-usage endpoints
  • Plan version deprecation based on usage data
• Capacity planning:
  • Understand growth patterns
  • Plan infrastructure scaling
• Client communication:
  • Provide usage reports to key API consumers
  • Help clients optimize their API usage

Practical Exercise: API Design Evaluation

// Create a new user
POST /createUser
Request Body: { "name": "John Doe", "mail": "john@example.com", "passwd": "secret123" }
Response: { "userId": 123, "status": "success", "message": "User has been created" }

// Get user information
GET /getUserInfo?id=123
Response: { "userId": 123, "name": "John Doe", "mail": "john@example.com" }

// Update user
POST /updateUser?id=123
Request Body: { "name": "John Smith", "mail": "john.smith@example.com" }
Response: { "status": "success", "message": "User has been updated" }

// Delete user
GET /deleteUser?id=123
Response: { "status": "success", "message": "User has been deleted" }

// Get users
GET /getUsers?page=1&size=10&sortBy=name&sortDirection=ASC&filter=John
Response: { 
  "totalUsers": 100, 
  "results": [
    { "userId": 123, "name": "John Doe", "mail": "john@example.com" },
    { "userId": 456, "name": "John Smith", "mail": "john.smith@example.com" }
  ]
}

// Get user posts
GET /getUserPosts?userId=123
Response: { "posts": [...] }
          

Summary

In this session, we've explored comprehensive best practices for API design:

• Naming and Consistency: Using intuitive, consistent resource names and conventions
• Error Handling: Providing clear, structured error responses with appropriate status codes
• Pagination, Filtering, and Sorting: Implementing flexible data retrieval options
• Versioning: Choosing and implementing an appropriate versioning strategy
• Documentation: Creating comprehensive, accurate, and usable API documentation
• Authentication and Security: Selecting appropriate authentication methods and following security best practices
• Performance: Optimizing response times, payload sizes, and leveraging HTTP caching
• Monitoring: Tracking key metrics to understand and improve API usage

Following these best practices results in APIs that are:

• Intuitive and easy to use
• Discoverable and well-documented
• Secure and reliable
• Efficient and performant
• Maintainable and evolvable

Remember that the best APIs aren't just technically correct—they provide an excellent developer experience. Consider the developers who will use your API as your users, and design with their needs and expectations in mind.

Additional Resources

• Swagger: Best Practices in API Design
• Google API Design Guide
• Microsoft REST API Guidelines
• Zalando RESTful API Guidelines
• Apigee: RESTful API Design - Nouns are Good, Verbs are Bad