[ADP-120] HTTP Headers

HTTP headers are metadata defined in requests and responses to formally describe them. API designers SHOULD possess knowledge about how to use existing HTTP headers to complete their API design, or create custom headers if no current header meets the requirements.

Key Points

• API designers SHOULD support common HTTP headers.
• Custom headers SHOULD be created only when existing headers fail to meet specific requirements.
  • DRAFT As X- is not recommended as a custom header prefix in the RFC, VVTK- SHOULD be used as the prefix for custom headers if necessary.
• DRAFT When a request header is inconvenient for a client to provide, the request header functionality MAY be replicated as query parameters. In such cases, the query parameter name should closely resemble the header name, adhering to all the rules governing query parameter names. For instance, the request header If-Match would be represented as the query parameter ifMatch.

  Casing

  If your project adopts a SNAKE_CASE convention for query parameter casing, the case would be if_match in this scenario.

Common HTTP Headers

See ADP-121

Custom Headers

See ADP-36

Best Practices

1. Be consistent in header usage across your API.
2. Validate and sanitize header values to prevent security vulnerabilities.
3. Use appropriate headers for authentication and authorization.
4. Leverage standard headers before creating custom ones.
5. Include relevant headers in your API documentation.

References

1. MDN Web Docs: HTTP headers
2. RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

Changelog

• 2024.09.30 Add header as query parameters, referred from IBM api docs