Is this a correct implementation of REST?

Question

Im steadily building the resources of my API, however after much research on the correct ways to build a RESTful API, I have been unable to find an example of how 'complex' requests should be received.

For example, as part of the login process (which is little more than an authentication key update), the following URI is dispatched by the client:

/api/auth/login

There are no values on the URI, the resource is /auth/ and the command being triggered is /login/. The actual login details are sent to the server Authorization header.

Now, what prompted me to ask this question is as I was writing a command to allow the client to get a reminder of how long the key is valid for, I was immediately drawn to getkeyexpiration or something similar as a command name.

Suddenly I felt that this doesn't sound like what I read about in the 6 constraints, this feels more like operation calls.

So, based on the above examples, is this still a RESTful API? I am concerned as I cannot think of a way to perform this by simply using URI resource names and appended values.

Thank you

EDIT:

From reading this: http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http

I am starting to understand that by naming resources and only resources with noun words, the context of how the server will operate becomes a lot clearer.

Regarding my above example:

/api/auth/login

I have used auth as a prefix of login, because that is the context of the resource. I am designing my system to be extendible and require a way to categorize resources on the URI level. Is there a standard way of doing this?

Answer 1

Your RESTful resources should be nouns, because HTTP provides the verbs.

I would suggest something like this instead:

/api/key

Which you can then POST to (with HTTP Authorization headers included) create a new key, returning something like this:

/api/key/1234ABCDBLAHBLAH

This is a key specific to your session, which you can then GET to retrieve details about it such as expiration time, etc. You will have to pass that key with each subsequent request, of course.

If the key stuff sounds clunky when discussed in the context of a RESTful API, it's because it usually is. Sessions are human/browser concepts, but RESTful APIs are application/integration concepts.

Since servers don't "log on" to other servers, this begs the question: if you're already OK with requiring the caller to pass an Auth header to your login API, why not just require it be passed for each API call, and forget the notion of keys altogether?