Lodewijk February 2016

API Desing: User Location

We're designing an API for a hand-held application that will be used in a hospital. The Url of the API is something restfull like /foo/bar/238. The response needs to be localized, so we'll use the Accept-Language header. However, some of the meta-data that will be returned by this API call, needs to be dependent on the nursing-unit where the application is used.

Given that the device knows the location, what would be the best way to send this information along with the request:

  • use a custom header (or a predefined, if such a thing exists)
  • tag it along in the querystring
  • something else...

Answers


Robert Bräutigam February 2016

Obviously both (headers, query parameters) would technically work, I think it comes down to personal preference somewhat.

I would argue against headers normally, since they are part of the infrastructure of HTTP, and they usually do not, or should not be part of the content. Also, clients can not really "discover" or "browse" using headers, and that goes against REST.

So, it must be then part of the URI, for example query parameters. This has the advantage, that it can be linked, tested, navigated, cached, etc.


Cássio Mazzochi Molin February 2016

Approach 1

Depending on your requirements, this information doesn't need to be exposed in a header nor in a query parameter.

I understand the users need to be authenticated to access your API. So, it's very likely you have an Authorization header to perform authentication (who the user is) and authorization (what the user can do).

Provided the users know the nursing unit they are working at, you can return the data according to the user who is currently authenticated in your API, without relying on query parameters or headers.

In this approach, you will need to persist in which nursing unit the user is currently working at. When a user moves from one nursing unit to another, just update the user resource with the nursing unit data:

PUT /api/users/me/nursing-unit
Content-Type: application/json
{
    "nursing-unit-id": 1 
}

Approach 2

If the first approach mentioned above doesn't suit your needs, using a query parameter is still a good approach.

The nursing unit parameter would fit better in a query parameter rather than in a custom header, once the URL should identify the resource itself in a REST API.

Post Status

Asked in February 2016
Viewed 1,193 times
Voted 5
Answered 2 times

Search




Leave an answer