PHP REST API Logic

Question

I have read several tutorials to introduce myself to know more about the rest API recently. However, I have got some doubts here and there and hope someone can help me out with this.

Reading the Beginner's Guide to HTML and REST, which states:

"Resources are best thought of as nouns. For example, the following is not RESTful:

1 /clients/add

This is because it uses a URL to describe an action. This is a fairly fundamental point in distinguishing RESTful from non-RESTful systems."

As such, I was wondering if for such cases where I have a user resource and to access it to do the usual insert/update/delete/retrieve

would be as follow:

www.example.com/users [get] <-- to retrieve all records
www.example.com/users/1 [get] <-- to retrieve record with id of 1
www.example.com/users/1 [put] <-- to update record with id of 1
www.example.com/user/1 [delete] <-- to delete record with id of 1
www.example.com/user [post] <-- to insert a new user record

This would have used up the 4 common verbs to make request.

What if I were to require a function such as login or perhaps in general any other types of action commands? How should the url be formed and how should the router redirect in such cases?

EDIT:

After looking at the various comments and answers. My take away from them is that the final solution would be somewhere along "use rest principles whenever possible and use the query string method with functions whenever not."

However, I was thinking of a slight variant of the implementation (not a restful implementation anymore, but following similar concepts) and wondering if it could have work out this way. Hope you guys can advice me on this.

Using the same authenticate/login function I would require to implement, could it be something along this instead:

www.example.com/users [get] <-- to retrieve all records
www.example.com/users/1 [get] <-- to retrieve record with id of 1
www.example.com/users/1 [put] <-- to update record with id of 1
www.example.com/user/1 [delete] <-- to delete record with id of 1
www.example.com/user [post] <-- to insert a new user record

as usual and if I were to require an action to be performed it will be as such:

[controller]/[action] --- user/authenticate [post] --- to login
[controller]/[id]/[action] --- user/1/authenticate [put] --- to logout

Will this work? Will there be any foreseen problems that I would face and are there similar implementations out there like this already? Please kindly advice!

Answer 1

REST is stateless so you need to put all the needed information into all queries. The idea is to work with the HTTP Verbs (GET, PUT, DELETE, POST - as you already descripted).

If you want an user authentification for your REST API, use something like HTTP Basic Auth, or your own Authentification. You have to send the Auth Information for every Request to the Server (stateless).

If you don't want an HTTP Basic Auth you can try some Token Authentification or any other auth.

Edit: If you want an "Check Login" Resource, build your own. For Example GET /account/checklogin with http basic auth header informations. The Result of this Request depends on your Authinformations.

Answer 2

There are some actions that are hard to model in a true RESTful way - but login, for instance, can be implemented using the following pseudo code:

GET the user rights whose userID is x and password is y
if (user rights found)
  assign rights to current user
else
  do not assign rights to user

See this question for how to retrieve the user rights. The point in this question is that you usually need multiple ways of accessing your resources. Some are based on IDs or well-know attributes, for instance:

• www.example.com/users/department [get] (get all users for a department)
• www.example.com/users/roleName [get] (get all users in a particular role)
• www.example.com/users/status/active [get] (get all users who are "active")

However, some ways of accessing users - especially when you need to combine two or more filtering attributes - are easier to manage using query string parameters. For instance:

www.example.com/users?department=xxx&role=yyy&status=active [get]

So, your REST API might expose a URL along the lines of:

www.example.com/users?userName=xxxx&password=yyy [get]

This URL would match the username and password parameters against the user database, and return either a 404 (if they don't match a known user), or a document representing the user, with their access rights.

Your client code then manages the current user's session - i.e. by setting the status to "logged in ", and associating the session with that user profile.

The key to making this work is assigning responsibility to the right layer - the API should not have to manage user sessions, that is the responsibility of the client application. There are cases where that doesn't work particularly well - not sure if yours is one, though.

If you really want to use a POST request, you can, of course, consider the "login" method the start of a session for that user. You could, therefore, do something like this:

www.example.com/session [POST] with parameters userID and password.

This would return a representation of the user profile and rights; it might also create documents accessible under the URLs

www.example.com/session/sessionID

www.example.com/session/user/ID/session

However, in general, it is a very dangerous idea to manage session state within the API - nearly always, you want the client session to be managed by the application interacting with the client, not by the API it talks to.

Answer 3

What if I were to require a function such as login or perhaps in general any other types of action commands? How should the url be formed and how should the router redirect in such cases?

It's not RESTful to have a login-action resource, but it is RESTful to provide a login-form resource:

/login-form

The HTML-form you return in the response functions as code-on-demand; you are supplying a configured piece of software to help the user supply their login credentials.

There would be nothing wrong with identifying the resource as just /login - I added the form-part to make the example clear.

You should avoid redirects where auth is required because it breaks the interface for clients other than web-browsers; instead you might either: provide a link to the login-form; or actually supply the login-form code in the response.

If you want to manage authentication, I prefer the approach of creating auth-tokens; in the case of Web-browsers I consider it acceptable to overload a single cookie for the purpose of helping the client supply the token with each request since they will have no other reasonable way to control the Auth header they send; obviously if you're writing your own client-application this is not a concern.

Answering your comments below, the purpose of the login form in an auth-token scenario is to create a new authentication token. So, thinking RESTfully, you model the users list of auth-tokens and POST a representation of the auth-token. This representation might contain the user's username and password. You might let the user choose their own token, or you might choose it for them and return this in the response. There is no action-URI required, and setting any cookies happens following successful creation of the new auth-token.

I recommend studying Amazon S3 REST API. It's slightly different than your requirement but its the best in-depth description of a potential REST authentication system I've seen set out:

http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAPI.html

Your thoughts on managing users RESTfully are accurate.

Hope it helps :)