Is it OK to use custom headers on an API?

[Ed McPadden]

We are creating a new API and we have a some things that we were thinking about setting using headers.

Some of the things we were thinking about passing as a header to the API calls are the following:

Client_id  (the App key)

X-TG-TENANT (we have a multi-tenant system and we thought that since this was setting the context for all of the API calls we'd just use a header instead of cluttering each resource on the API with this as a query string parameter.

Someone today questioned why I was using a header to pass this.   He agreed that it seemed like a good idea because it set up the context for all of the API calls but was concerned about using headers because they could get stripped out somewhere between the caller and our API server.

Is this a real concern?  Is this just a bad idea?  Or is it OK to have custom headers on an API.

[Darrel Miller]

Hey Ed,

 

In my opinion there is nothing wrong with using custom headers.  I have seen this concern about proxies stripping headers before but I’m not convinced that it is as big a problem as it is rumored to be.  There are certain headers that must be stripped off by intermediaries like Connection and Transfer-Encoding, but that is because they are defined as “hop-by-hop” and not intended to be passed along.

There are some issues where headers with underscores get stripped by nginx by default (http://stackoverflow.com/questions/23231063/simple-nginx-reverse-proxy-seems-to-strip-some-headers)

People have had concerns about Google’s proxy stripping headers, but according to their tech lead, it doesn’t (http://stackoverflow.com/a/28355894/6819).

 

I would recommend dropping the x- off the beginning of the custom header.  Although it is common to see the prefix, it was deprecated a few years ago.  https://tools.ietf.org/html/rfc6648

 

For the API key, I do think it is better to use a header than the URL.  Although, the best place to put security keys is in the Authorization header.   I’ve written about this before http://www.bizcoder.com/where-oh-where-does-the-api-key-go

 

One other issue to consider regarding putting values in headers is HTTP caching.  By default, caches use the URL as part of the primary cache key.  If you move the tenant identifier out of the URL then in order to be able take advantage of caching, then you will need to include that header name in the vary header, so that it becomes part of the secondary cache key.  The only problematic part about that is some caches have very limited support for the vary header. 

 

Hope that provides some more fuel for the conversation.

 

Regards,

 

Darrel

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Andrew B]

By contrast we use an approach at the other end of the scale, putting the tenant name into the domain, e.g.:

GET acme.someapp.com/someAPI

We did this to meet requirements (that you may not have) such as allowing the tenant to have vanity URLs (e.g. worldsbestjobs.com is a CNAME for acme.someapp.com).

It works fine but a serious downside of the way we do it is a lot of expense buying SSL wildcard certs.

Using a header for tenant as you suggest makes me a little nervous that it might be easier for you to slip up and leak one tenant's information into another tenant e.g. if some intermediate cache ignores the header, and then one tenant gets the results previously cached for a different tenant. You could prevent that in your stack, but what if two of your tenants were (say) co-located at a serviced office or somewhere and both behind a common web cache and that cache didn't pick up on your header. Not your problem you could rightfully argue I guess.

Using a header might also make examining logs (and using common log analysis tools) a little harder, since the tenant is not visible in the URL.

[Ram Vemuri]

Hi Ed,

A custom header is certainly one way to achieve this. Of course, using a header alone for identifying the owner is a security risk. You would also verify on the server that the specific client key has been granted access to that account for that api. So definitely think about security on that one.

Depends on your situation but custom domain that was suggested is one way to go but could be hard to manage on ops side. An analogy to this is to push this down to the path to the REST resource such as multi-tenant-app.com/customer/stuff. It aligns with partitioning customer data in a multi-tenant system.

-ram

[Ed McPadden]

Thanks Darrel.  This really helps!

[Ed McPadden]

Good idea Ram.  I will bring this up at work.