re: Where to Put Response Metadata - Envelope or HTTP Headers? VIEW POST

VIEW FULL DISCUSSION
 

X- headers are deprecated since 2012, and I dont think that result logic should exists in the headers anyway, so my bet would be in the response.

 

Thanks for pointing out my mistake! I corrected it. Unfortunately I'm not sure if I can follow why pagination information or follow-up links should not be part of response headers. We already have a lot of meta information in HTTP response headers that describes the content such as content type, language, or content range which is similar to pagination... can you explain why that kind of information doesn't belong there?

 

I see the next page links as other resource identifiers, as business logic and related to that specific request. I see them oposite to metadata like language and encoding, which are to describe the response and API as overall.

Also based on the logic that one client dont use it (infinite scroll) is not valid, you did not remove it just moved the information to another section of the HTTP response.

As for the data naming and common implementation mistakes I say that the API server and client implementations are details that should be automatically generated, I use Open API/swagger generators for that.

 

RFC 6648: Deprecating the "X-" Prefix and Similar Constructs in Application Protocols

The deprecation of X- is mainly concerning possible standardization of these items. But:

When it is extremely unlikely that some parameters will ever be standardized. In this case, implementation-specific and private-use parameters could at least incorporate the organization's name (e.g., "ExampleInc-foo" or, consistent with [RFC4288], "VND.ExampleInc.foo") or primary domain name (e.g., "com.example.foo" or a Uniform Resource Identifier [RFC3986] such as "example.com/foo"). In rare cases, truly experimental parameters could be given meaningless names such as nonsense words, the output of a hash function, or Universally Unique Identifiers (UUIDs) [RFC4122].

I do think headers are the place to put this information, it always has. There is just the rather time consuming part of figuring out the proper header usage. To simply put an X- in front of the header name is a bad practice (see above RFC for the reasoning.)

What you need to do

  1. Find an existing, or work in progress, standard; and use it.
  2. Think really really hard if your custom entry is standard worthy.
  3. Only then use a vendor prefix. e.g. DevTo-Gizmo

As for the example of this article, there is a standard RFC 5988 to provide referential information in the HTTP headers. Note that they are working on RFC 8288 which will replace it. So it is probably best to follow RFC 8288. (And regularly check back for changes).

 

Great explanation, thank you. I will also keep an eye on RFC 8288.

code of conduct - report abuse