HTTP header for indicating required stylistic property for the response body

Question

What HTTP header should I use for specifying stylistic properties of an HTTP response, specifically the case of keys in a JSON object? A note: I am developing a REST API where I would like clients to provide an expected case, for example camelCase or snake_case.

When camelCase is specified a response would look like:

{
  "peopleUrl": "…",
  "postsUrl": "…"
}

When snake_case is specified a response would look like:

{
  "people_url": "…",
  "posts_url": "…"
}

The headers I’ve been looking at are Expect and Prefer. Expect is described as mandatory configurations a server must comply with or error, and Prefer is described as optional configurations. The specific syntax I was looking at is:

Expect: case=camel

or:

Prefer: case=camel

Currently, I’m feeling like Expect is the best because it requires the configuration. However, while in RFC 2616 an extension mechanism for Expect is provided, however in RFC 7231 this extension mechanism was removed and only the 100-continue field is allowed (scroll to the next page to see the note providing the warrant). The Prefer header was specified in RFC 7240 and does appear to have an extension mechanism.

Which header is best for this configuration option? Am I looking in the wrong direction with Expect and Prefer?

_"I would like clients to provide an expected case"_ - **why?** Just document one casing, and let your clients stick to that... Anyway, as you can read in RFC 7240, you'll have to register `Prefer` extensions with IANA. — CodeCaster, Mar 24 '16 at 15:44
When you have an API which needs to serve data to multiple different platforms, it's helpful to let them choose which format they want. A JS client may want `camelCase` whereas a PHP client might want `snake_case`. Even if this is a bad idea, finding an appropriate header is still a valid question. — Calebmer, Mar 24 '16 at 15:47
You're the service provider, you determine the format. I'm not saying it's an invalid question, just a silly one. Don't forget about the overhead this will cause on your side. Anyway there's no existing header you can leverage to do this. — CodeCaster, Mar 24 '16 at 15:48

score 1 · Answer 1 · answered Mar 26 '16 at 22:11

As some of the comments indicate, there probably isn't an existing HTTP header name, defined in the HTTP RFCs, which would cover/handle your use case. Using Expect or Prefer, with well-defined semantics that don't quite cover your needs, may lead to more pain/frustration than you'd like; those headers might be handled specially by existing clients, servers, and proxies in ways that you do not want/expect.

That said, there is nothing preventing you from using your own custom X- header for requests and responses, e.g. X-JSON-KeyStyle:

GET /path/to/resource HTTP/1.1
Host: ...
X-JSON-KeyStyle: camel
...

And then your response would indicate the style used in the returned data:

HTTP1/1 200 OK
...
X-JSON-KeyStyle: camel
...

By specification, any header names prefaced with X- are deliberately not handled/covered, and are for uses such as this. With this approach, then, you would only need document your custom HTTP header, for use by clients of your REST API.

Hope this helps!

HTTP header for indicating required stylistic property for the response body

1 Answers1