[ADP-48] API Robustness

reviewing phase 1

This principle needs more practice content.

Overview

API robustness refers to the ability of an API to handle a wide range of inputs and usage scenarios without failure. When designing an API, a key consideration is whether to adopt a strict or lenient approach to input validation, error handling, and overall design philosophy. This article discusses the benefits and drawbacks of both approaches and provides examples to illustrate each.

Guidance

• SHOULD be consistent about API robustness decision in the same application

Strict API Guidelines

Definition

A strict API enforces rigorous validation and adherence to defined standards. Every request must conform precisely to the expected format, and any deviation results in an error.

Benefits

1. Consistency: Ensures all inputs are standardized, reducing the risk of unexpected behaviors.
2. Security: Minimizes vulnerabilities by validating all inputs strictly, protecting against malformed requests and potential attacks.
3. Predictability: Clients can rely on a well-defined contract, making integration and debugging easier.

Drawbacks

1. Rigidity: May be less forgiving of minor deviations, potentially leading to higher error rates for clients.
2. Complexity: Requires detailed documentation and extensive validation logic, increasing development and maintenance efforts.

Example

Consider an API for creating a user profile with the following strict requirements:

• Endpoint: POST /users

• Payload:

  {
      "username": "string (alphanumeric, 3-20 characters)",
      "email": "string (valid email format)",
      "age": "integer (18-100)"
  }

Any request that fails to meet these criteria will result in a 400 Bad Request response with a detailed error message:

{
  "type": "https://example.com/problems/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "The 'username' field must be alphanumeric and between 3 and 20 characters."
}

Lenient API Guidelines

Definition

A lenient API allows for more flexibility and tolerates deviations from the expected input format, often implementing defaults or forgiving minor errors.

Benefits

1. Flexibility: Accommodates a broader range of inputs, reducing the likelihood of client errors.
2. Ease of Use: Simplifies integration for clients, as minor mistakes are less likely to result in errors.
3. User Experience: Provides a smoother user experience by handling minor issues gracefully.

Drawbacks

1. Inconsistency: Can lead to variations in input formats, making the API less predictable.
2. Security Risks: More forgiving input validation may expose the API to security vulnerabilities.
3. Complexity in Handling: Requires robust error handling and defaulting mechanisms, which can be complex to implement.

Example

Consider a lenient approach for the same user profile creation API:

• Endpoint: POST /users

• Payload:

  {
      "username": "string (optional)",
      "email": "string (optional, valid email format)",
      "age": "integer (optional, defaults to 18)"
  }

If a client omits the username or email fields, the API will still create the user profile, assigning default values where necessary:

{
  "id": "12345",
  "username": "defaultUser",
  "email": "user@example.com",
  "age": 18
}

Balancing Strictness and Leniency

Best Practices

1. Critical Fields: Apply strict validation to critical fields that impact core functionality or security, such as authentication tokens or financial data.
2. Optional Fields: Allow leniency for optional fields, providing defaults or inferring values where appropriate.
3. Error Handling: Implement comprehensive error handling and logging to monitor and address potential issues arising from lenient inputs.
4. Documentation: Clearly document the expected input formats, validation rules, and any lenient behaviors to guide clients in using the API correctly.

Example

A balanced approach for user profile creation might involve strict validation for the email field (to ensure a valid communication channel) and lenient handling of the username and age fields:

• Endpoint: POST /users

• Payload:

  {
      "username": "string (optional, alphanumeric, 3-20 characters)",
      "email": "string (required, valid email format)",
      "age": "integer (optional, defaults to 18)"
  }

Responses would reflect a combination of strict and lenient handling:

• Strict Error:

  {
      "type": "https://example.com/problems/invalid-input",
      "title": "Invalid input",
      "status": 400,
      "detail": "The 'email' field must be a valid email format."
  }

• Lenient Handling:

  {
      "id": "12345",
      "username": "defaultUser",
      "email": "user@example.com",
      "age": 18
  }