[ADP-364] Custom Header Fields Design

Guidance

Header Naming

• SHOULD NOT use the "X-" prefix for custom header names.

  TIP

  This practice has been deprecated as per IETF recommendations (RFC 6648).

  INFO

  For custom headers that have become conventions, keep their names, such as: X-Request-Id.

• SHOULD use clear, descriptive names that convey the purpose and usage of the header.
• SHOULD maintain consistency in header naming conventions across the application.
• SHOULD follow a pattern that matches the application's overall naming conventions for readability and maintainability.
• DRAFT SHOULD register custom headers in the internal API portal registry to ensure consistent use across different projects, similar to the IANA registry approach.
• SHOULD update custom headers to the shared OpenAPI headers.yaml and update the version number, please refer to ADP-767: Shared Common Headers.
• SHOULD evaluate existing standard headers before creating a custom one. Please refer ADP-121: Common Headers.
  • MUST use an existing standard header if it meets the requirements instead of creating a new custom header.

Examples

DON'T:

X-User-Role: admin

DO:

User-Role: admin

Reference

• https://datatracker.ietf.org/doc/html/rfc6648