REST GET requests, verbs and apikey

Question

I want to create a flexible API Rest server. I will allow the clients to authenticate using HTTP or an APIKEY.

My question is: what is the correct way to add the apikey to a GET request? My problem is the apikey pollutes the url.

I imagine something like this : /book/1/apikey/s4cr4t !

Answer 1

In my opinion you should only use the Authorization header. That's what it is there for.

Putting it in the URL is a bad idea because:

a) as you said it pollutes the URL
b) if you decide to go SSL for security then the API will still appear in log files
c) caches will end up creating multiple copies of the same representation, one for each api key.

For more information on creating your own Authorization scheme go here.

Answer 2

Credentials may be passed using the Authorization header:

GET http://domain.com:/book/1
Authorization: apikey="s4cr4t"

Answer 3

It all depends on how far you want to go but the mechanics stays the same:

Context

The goal is to identify the client with some level of security. (Note: Security is another detailed discussion). Remember that one if the “features” of REST is to be stateless: That means no session state on the server except for resources. To keep the client stateless, it needs to supply on each request enough information that the request is independent. It must give the server a way to identify the client such as a username/password, API Key or token.

You have various options to do this so here are some:

Add HTTP headers to identify the client

Here one can use the Authorization header and send it with each request. There are various authentication schemes but stick to the standard ones such as Basic Auth. Here you would probably stick to SSL. The authentication process generates a kind of token if you like.

You can also make use of a cookie. The cookie must contain no information except that it is a “pointer or key” to a stateful session resource on your server (note: session it a resource which is “rest-legal”). You can create this resource by doing a PUT (+info) with response 200 OK or POST (+info) with a response of 201 Created and Location: /sessions/123334. The session can then be validated by the server such as timeout, valid client ip address, api key etc.

With the method above, you can also define a customer header such as Api-Key: XXXX. But then you limit yourself to special client. Set-Cookie are “well known” headers so browser will handle them kind of transparently. The authentication process can then be done by following links and filling in forms (PUT + POST) to authenticate (create session resource).

Encode an identifier in the content

Here you are free to do what you want too. Just add a field/token/id to your content and let the server verify it.

A RESTful API does application flow by resolving links. See also HATEOAS and Fielding's words. This also applies when you have a separate process of logging in to the application.

Do not encode any data in the URIs. (Out of band information)