ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-355] Request with Preference ​

Overview ​

The Prefer header is a request-only header used to communicate client preferences to the server. It allows clients to influence how the server processes and responds to their requests.

For general guidance on the Prefer header, please refer to ADP-136: Prefer.

Benefits ​

  1. Efficiency: Reduces bandwidth and processing time by allowing clients to specify their response format preferences.
  2. Flexibility: Enables clients to tailor requests based on their current needs, improving overall user experience.
  3. Scalability: Allows servers to handle requests more efficiently by delivering only necessary data.

Custom Preferences ​

Custom preferences allow clients to define specific behaviors or response formats not covered by standard preferences. These can be tailored to unique application requirements.

Syntax ​

http
Prefer: foo=value, bar
  • Keys should be in kebab-case.
  • Values are optional; if a preference is designed to have a value, it should be enumerable.

Example ​

http
Prefer: handling=strict, timezone=Asia/Taipei

Note: There's no standard header for timezone-based requests. Adding it as a custom preference is an option.

Guidelines ​

  • SHOULD respect Request with Preference

  • MUST document if your API supports Preference

  • MUST return with Preference-Applied header to inform the client of accepted preferences

    Example:

    http
    PATCH /my-document HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation

[{"op": "add", "path": "/a", "value": 1}]

HTTP/1.1 200 OK
Content-Type: application/json
Preference-Applied: return=representation
Content-Location: /my-document

{"a": 1}

  • MUST NOT return errors if there's no relevant action for the client's preference

  • SHOULD document customized preferences in your API documentation and describe how the server respects the preference

  • DRAFT SHOULD register custom preferences in the internal API portal

  • SHOULD re-use custom preferences for requirements before inventing new ones

Examples ​

Minimal Response ​

http
POST /robots/{robot-id}/move HTTP/1.1
Host: example.com
Prefer: return=minimal
http
HTTP/1.1 202 Accepted

Asynchronous Processing ​

http
POST /robots/{robot-id}/stop HTTP/1.1
Host: example.com
Prefer: respond-async

OpenAPI 3.1.0 Specification ​

To document custom preferences in your OpenAPI 3.1.0 specification, follow these guidelines:

  • Define the Prefer header in the components.parameters section:

    yaml
    components:
  parameters:
    Prefer:
      name: Prefer
      in: header
      description: Client preferences for server behavior
      schema:
        type: string
      example: "handling=strict, timezone=Asia/Taipei"

  • Reference this parameter in relevant operations:

    yaml
    paths:
  /example:
    get:
      summary: Example operation
      parameters:
        - $ref: '#/components/parameters/Prefer'
      responses:
        '200':
          description: Successful response
          headers:
            Preference-Applied:
              schema:
                type: string
              description: Indicates which preferences were applied

  • For APIs supporting specific custom preferences, provide more detailed descriptions:

    yaml
    components:
  parameters:
    Prefer:
      name: Prefer
      in: header
      description: |
        Client preferences for server behavior. Supported preferences:
        - handling=strict: Enforce strict data validation
        - timezone=<tz>: Use specified timezone for date/time operations
      schema:
        type: string
      example: "handling=strict, timezone=Asia/Taipei"

  • For complex preference settings, use an object type schema:

    yaml
    components:
  parameters:
    Prefer:
      name: Prefer
      in: header
      description: Client preferences for server behavior
      content:
        application/json:
          schema:
            type: object
            properties:
              handling:
                type: string
                enum: [strict, lenient]
              timezone:
                type: string
                pattern: '^[A-Za-z_]+/[A-Za-z_]+$'
          example:
            handling: strict
            timezone: Asia/Taipei

These examples demonstrate how to describe custom preferences in OpenAPI 3.1.0. Adjust and expand these definitions based on your specific API requirements.

References ​

Design Reference ​