Here we are, ready for another edition of API Management Best Practices, Tips, and Tricks. Today, we will address another helpful Best practice, Tip, and Trick that you must consider when implementing your APIs: naming conventions.
#7 HTTP Headers structure and naming convention
HTTP headers are key-value pairs sent in HTTP requests and responses, providing metadata about the request or response. They define how data should be processed, secured, and interpreted between the client and server.
A very common example of HTTP Headers in a Request is the Content-Type. This header indicates the format of the request body, for example:
- Content-Type: application/json
To ensure consistency with the “out-of-the-box HTTP header” (standard HTTP/1.1 and HTTP/2 header fields defined by the IETF in the HTTP specifications), readability, and maintainability, the following best practices should be applied to HTTP Headers:
- Use Pascal-Case (First letter capitalized in each word). HTTP headers should follow a Pascal-Case naming convention, where each word starts with an uppercase letter and words are separated by hyphens.
- ✅ Content-Type
- ❌ content-type – Incorrect because you shouldn’t use Lowercase.
- ❌ Content_type – Incorrect because underscores shouldn’t be used.
- ❌ ContentType – Incorrect, despite being possible, because words should be split by a hyphen.
- Be Descriptive & Meaningful – Headers should clearly define their purpose.
- ✅ Cache-Control – It defines the caching policy for requests and responses.
- ❌ X-Data – This is too vague
- Use Standardized Headers when possible. Avoid creating custom headers unless necessary. If possible and makes sense, use the well-known headers defined in the HTTP standards, like Content-Type, Accept, Authorization, and Cache-Control.
- For Custom Headers, use X- or a vendor prefix. If you must create custom headers, use X- or a company-specific prefix:
- ✅ X-Name-Of-The-Header
- ✅ DevScope-Name-Of-The-Header
Know more about naming conventions and API best practices in my whitepaper: Mastering API Best Practices Enforcing Best Practices with Azure API Management.
I hope you enjoy this tip and stay tuned for the following Azure API Management Best practices, Tips, and Tricks.
If you liked the content or found it helpful and want to help me write more, you can consider buying (or helping to buy) my son a Star Wars Lego set.
