REST APIs: custom HTTP headers vs URL parameters

Question

When do you use custom HTTP headers in the request part of a REST API ?

Example:

Would you ever use

GET /orders/view 
(custom HTTP header) CLIENT_ID: 23

instead of

GET /orders/view/client_id/23 or 
GET /orders/view/?client_id=23

score 165 · Accepted Answer · edited Sep 08 '17 at 19:02

165

The URL indicates the resource itself. A "client" is a resource that can be acted upon, so should be part of the base url: /orders/view/client/23.

Parameters are just that, to parameterize access to the resource. This especially comes into play with posts and searches: /orders/find?q=blahblah&sort=foo. There's a fine line between parameters and sub-resources: /orders/view/client/23/active versus /orders/view/client/23?show=active. I recommend the sub-resource style and reserve parameters for searches.

Since each endpoint REpresents a State Transfer (to mangle the mnemonic), custom headers should only be used for things that don't involve the name of the resource (the url), the state of the resource (the body), or parameters directly affecting the resource (parameters). That leaves true metadata about the request for custom headers.

HTTP has a very wide selection of headers that cover most everything you'll need. Where I've seen custom headers come up is in a system to system request operating on behalf of a user. The proxy system will validate the user and add "X-User: userid" to the headers and use the system credentials to hit the endpoint. The receiving system validates that the system credentials are authorized to act on behalf of the user, then validate that the user is authorized to perform the action.

edited Sep 08 '17 at 19:02

Alexis Wilke

19,179
10
84
156

answered Feb 07 '12 at 00:12

Nialscorva

2,924
2
15
16

1

Thanks for such a comprehensive answer ! Would you still use the X-User for a mobile API where the risk of having an evil proxy (that strips off the header) is still high ? – Vasile Cotovanu Feb 14 '12 at 07:50
3

No, the usage of X-User that I mentioned is in system to system connections where the system is acting on behalf of a third party. For example, User U talks to Server A. Server A presents credentials to Server B with an X-User header to say "Use my credentials to check that I'm authorized to perform this action on behalf of User U." This comes up in Service Oriented Architectures, and usually you're using HTTPS. A mobile platform should almost always be the User himself acting, and use appropriate first person credentials for the transaction. – Nialscorva Feb 15 '12 at 00:08
9

The third paragraph is one of the most informative answers I've read on SO ;-) – Alistair77 May 31 '13 at 11:36
1

@Nialscorva Great explanation! what if I'd like the user to interact with my API via an authorised container (like my mobile app)? What I'm doing now is that my mobile app is not authorised to perform any action on its own and neither the end user.. both credentials must be present if the user is willing to perform an action. – bolbol Jun 03 '13 at 03:33

score 24 · Answer 2 · answered Aug 26 '21 at 16:35

24

Use HTTP Headers for sending,

Directives ( read the input in JSON format )
Metadata ( who is making the request )
Common data to be sent on every request ( like Authentication, session )

Use Path Parameters to make,

Specific requests on a resource ( /country/state/city )

They must form a logical hierarchy

Use Query Parameters for sending,

Action requests on a resource ( like pagination, filters )

answered Aug 26 '21 at 16:35

KJ Sudarshan

2,694
1
29
22

1

Nice directives – Somaiah Kumbera May 19 '22 at 13:38

score 9 · Answer 3 · answered Feb 06 '12 at 23:56

9

I would only use a custom header when there is no other way to pass information by standard or convention. Darren102 is explaining the typical way to pass that value. Your Api will be much more friendly by using typical patterns verse using custom headers.That's not to say you won't have a case to use them, just that they should be the last resort and something not already handled by the HTTP spec.

answered Feb 06 '12 at 23:56

suing

2,808
2
16
18

Wholeheartedly agree... never re-invent the wheel if there is a standard way to accomplish a task. – Alessandro Santini Feb 07 '12 at 00:02

score 5 · Answer 4 · edited Jul 23 '17 at 02:17

When do you use...HTTP headers in the request part of a REST API?

Authentication: GUIDs, basic authentication, custom tokens, etc. e.g., Basic Authentication with a Guid token for REST api instead of username/password

If you get involved in passing tokens or other authentication-like information between domains covered by PCI-DSS or other security rules you may also have to bury parameters because some regulations explicitly require authentication elements to stay out of URLs that could be trivially replayed (from browser histories, proxy logs, etc.).

Christophe Roussy · Answer 5 · 2021-02-11T10:07:06.323

5

Custom headers have the following advantages:

Keeps urls free from security stuff (safer, not in browser/proxy caches)

Personally I would only use those internally between my own web code and my own web server in case I need something special.

edited Feb 11 '21 at 10:07

answered Dec 09 '15 at 11:02

Christophe Roussy

16,299
4
85
85

3

they can also be silently stripped/filtered by proxies – fusi Jan 07 '16 at 09:58
@fusi good point ... here is topic about it: https://stackoverflow.com/questions/20820572/under-what-conditions-are-http-request-headers-removed-by-proxies – Christophe Roussy Jul 26 '20 at 13:25

score 1 · Answer 6 · answered Feb 06 '12 at 23:52

There is no standard for REST however the accepted way would be

GET /orders/view/23

Not using the custom headers and hence the 23 after view assumes to be the id hence you would have a function that takes in the id and hence produces just that information.

score 1 · Answer 7 · answered Feb 06 '12 at 23:53

1

I wouldn't use custom headers as you don't know if any proxies will pass those on. URL based is the way to go.

GET /orders/view/client/23

answered Feb 06 '12 at 23:53

Antony Scott

21,690
12
62
94

5

I wouldn't recommend custom headers either, but broken proxies are not the reason. The the proxy is broken it should be fixed. – Julian Reschke Feb 07 '12 at 08:59

score 0 · Answer 8 · edited May 23 '17 at 10:31

0

You can use custom headers to include more information about a partially processed request considering that Enveloping is not a good practice. The headers are secure.

edited May 23 '17 at 10:31

Community

1
1

answered Mar 04 '16 at 12:37

Anwar Husain

1,414
14
19

score 0 · Answer 9 · answered Feb 06 '12 at 23:54

0

Definitely OK:

GET /orders/view/client_id/23 or 
GET /orders/view/?client_id=23

Also OK:

GET /orders/view/23 or

I would think this would be OK, too:

POST /orders/view 
(custom HTTP header) CLIENT_ID: 23

answered Feb 06 '12 at 23:54

paulsm4

114,292
17
138
190

REST-ful POST response should be a HTTP 303 with Location header set to something like "/orders/view/23". – Rich Remer Jul 18 '15 at 22:47

REST APIs: custom HTTP headers vs URL parameters

9 Answers9

Linked