Rest application header based vs path based service routing

Question

i have a rest API that is a front end to a more complex SOAP based service. The soap based service uses extended(custom) WSA-addressing headers in order to perform its routing. The extension of the WSA-Addressing adds two header parameters country and city for example. Since the routing elements are mandatory I need to pass them in some form to the REST API and then use them on the SOAP client in order to get the routing right. I have two options with regards of the REST API:

1. Pass them as HTTP headers
2. Pass them as path parameters. Lets say that for example the two routing parameters are land and city and my REST resource ID is 123456.

them my GET will look like:

getResource/country/city/123456

If I use headers then it will be:

getResourfce/123456

It should be noted that the ID alone is uniquly identifying a resource , so the country and city are for routing only.

If I was using SOAP there would have been no question that I will use HEADERs. What is the situation when REST is used with regards of routing.

What is the proper way of expressing this parameters ? Headers or path elements ?

Answer 1

It should be noted that the ID alone is uniquly identifying a resource , so the country and city are for routing only.

Sounds like the ID alone doesn't actually uniquely identify the resource, since if the underlying SOAP service requires them to find the resource and only having the ID can't identify the resource, they are in fact required to identify the resource.

Having IDs that are not shared across resources is not the same thing as the ID itself being able to uniquely identify a resource.

Even if /Canada/Toronto/12345 and /Ireland/Dublin/12345 will never happen because the IDs are not shared you still need this country and city information to get the correct resource.

So I would put them in the URL.

Don't put them in the header. This information has nothing to do with the HTTP transport level.

Answer 2

Ultimately it's up to you to decide, both options are possible.

At first I didn't like the header approach but then I found two examples of header usage in RESTful services that make it look sensible:

• Authorization: headers are used to control access rights to resources, including possibly different visibility of fields.
• Accept: headers can be used to select the presentation of resources, i.e. the same resource could be presented as JSON, XML, or HTML data.

However, if each resource is only accessible with one specific country/city combination and the client needs to know that usa/new_york is needed for 11112222 but spain/madrid for 11112233, these should go into the path. Header values are not part of a URI, and remembering or finding out which country and city need to be passed in the request for a specific resource should not be the client's responsibility.

Answer 3

There is absolutely noting wrong about passing parameters in headers. Any decent REST framework will support it. It's not typically a first choice but there is one situation where you definitely should pass your parameters in headers:

RESTful web services should be careful to prevent leaking credentials. Passwords, security tokens, and API keys should not appear in the URL, as this can be captured in web server logs, which makes them intrinsically valuable.

• In POST/PUT requests sensitive data should be transferred in the request body or request headers.
• In GET requests sensitive data should be transferred in an HTTP Header.

While the above refers directly to security data, the same logic would apply to any other kind of sensitive information e.g. credit card numbers.