162

I was designing a web app and then stopped to think about how my api should be designed as a RESTful web service. For now, most of my URI's are generic and might apply to various web apps:

GET /logout // destroys session and redirects to / GET /login // gets the webpage that has the login form POST /login // authenticates credentials against database and either redirects home with a new session or redirects back to /login GET /register // gets the webpage that has the registration form POST /register // records the entered information into database as a new /user/xxx GET /user/xxx // gets and renders current user data in a profile view POST /user/xxx // updates new information about user

I have a feeling I'm doing a lot wrong here after poking around on SO and google.

Starting with /logout, perhaps since I don't really GET anything - it may be more appropriate to POST a request to /logout, destroy the session, and then GET the redirect. And should the /logout term stay?

What about /login and /register. I could change /register to /registration but that doesn't alter how my service fundamentally works - if it has deeper issues.

I notice now that I never expose a /user resource. Perhaps that could be utilized somehow. For instance, take the user myUser:

foo.com/user/myUser

or

foo.com/user

The end user doesn't require that extra verbosity in the URI. However, which one is more appealing visually?

I noticed some other questions here on SO about this REST business, but I would really appreciate some guidance on what I've laid out here if possible.

Thanks!

UPDATE:

I would also like some opinions on:

/user/1

vs

/user/myUserName
Improve this question
1

7 Answers 7

Reset to default
175

RESTful can be used as a guideline for constructing URLs, and you can make sessions and users resources:

  • GET /session/new gets the webpage that has the login form
  • POST /session authenticates credentials against database
  • DELETE /session destroys session and redirect to /
  • GET /users/new gets the webpage that has the registration form
  • POST /users records the entered information into database as a new /user/xxx
  • GET /users/xxx // gets and renders current user data in a profile view
  • POST /users/xxx // updates new information about user

These can be plural or singular (I'm not sure which one is correct). I've usually used /users for a user index page (as expected), and /sessions to see who is logged in (as expected).

Using the name in the URL instead of a number (/users/43 vs. /users/joe) is usually driven by the desire to be more friendly to the users or search engines, not any technical requirements. Either is fine, but I'd recommend you are consistent.

I think if you go with the register/login/logout or sign(in|up|out), it doesn't work as well with the restful terminology.

Improve this answer
Sign up to request clarification or add additional context in comments.

12 Comments

Awesome! I like how you noun'ed those resources; that's pretty clean. Although, from what I've heard, isn't appending /new to GET /session/ non RESTful? I've heard that the verbs are typically left to the HTTP verbs (GET, POST, etc).
@Zach new is not a verb. In this case it's a subresource of session.
Personally I don't like the idea of having the routes which return the form (/new). This breaks the separation between the view and business logic. Tha said, without the /new routes the suggested one look perfect.
This whole answer is just plain wrong. REST is about getting data. So first of all GET /session/new should not be getting a web page, but a list of all current sessions. Not even talking about the wrong /new being appended. Second, POST is for creating resources. I know this post is old but for people reading this in 2020: You really should not be following these recommendations. Follow more official best practices: https://restfulapi.net/resource-naming/
This is Rails style from 9 years ago about how to structure HTML page URLs. I agree doesn't make sense if you are building an API, but that's not the context of the question. These days, you will be considering more baked auth protocols.
|
77

Sessions aren't RESTful

  • Yes, I know. It's being done, usually with OAuth, but really sessions aren't RESTful. You shouldn't have a /login /logout resource primarily because you shouldn't have sessions.

  • If your going to do it, make it RESTful. Resources are nouns and /login and /logout aren't nouns. I would go with /session. This make creation and deletion a more natural action.

  • POST vs. GET for sessions is easy. If you are sending user/password as variables, I would use POST because I don't want to have the password sent as part of the URI. It will show up in logs and possibly be exposed over the wire. You also run the risk of having software fail on GET args limitations.

  • I generally use Basic Auth or no Auth with REST services.

Creating users

  • It's one resource, so you shouldn't need /register.

    • POST /user - Creates a user if the requestor cannot specify the id
    • PUT /user/xxx - Create or update a user assuming you know the id beforehand
    • GET /user - lists x user ids
    • GET /user/xxx - GETs the details of the user with id xxx
    • DELETE /user/xxx - Delete the user with id xxx

  • Which kind of ID to use is a hard question. You have to think about enforcing uniqueness, about reuse of old ids that were DELETEd. For example, you do not want to use those ids as foreign keys on a backend if ids are going to be recycled (if at all possible). You can have a lookup though for external/internal id conversion in order to mitigate backend requirements.

Improve this answer

5 Comments

This is the best answer. /login and /logout aren't resources and break the idea of REST.
Authentication != Session
Yes, Fielding's thesis states in section 5.1.3 that "[s]ession state is [...] kept entirely on the client." Further, I would argue that, ideally, authentication should also be stateless on the server side, i.e., rather than storing active "authentication tickets" in a database, the server should be able to verify an authentication credential just based on the credential itself, e.g. by using a self-contained cryptographic token in conjunction with a private key. So, instead of a /session resource one could introduce an /authentication resource, but it doesn't really solve the problem either...
Actually, /login and /logout are nouns. I assume you're thinking of /log_in and /log_out.
"I would go with /session. This make creation and deletion a more natural action." I agree with this, but which HTTP verb should be used to log in (i.e. initiate the session)? GET? POST? PUT? Assuming DELETE would be used to log out.
73
+150

One thing sticks out in particular as not REST-ful: the use of a GET request for logging out.

(from http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods)

Some methods (for example, HEAD, GET, OPTIONS and TRACE) are defined as safe, which means they are intended only for information retrieval and should not change the state of the server. In other words, they should not have side effects, beyond relatively harmless effects such as logging, caching, the serving of banner advertisements or incrementing a web counter. [...]

[... H]andling [of GET requests] by the server is not technically limited in any way. Therefore, careless or deliberate programming can cause non-trivial changes on the server. This is discouraged, because it can cause problems for Web caching, search engines and other automated agents [...]

As for logging out and redirecting, you could have a post to your logout URI give a 303 response redirecting to the post-logout page.

http://en.wikipedia.org/wiki/Post/Redirect/Get

http://en.wikipedia.org/wiki/HTTP_303

Edit to address URL design concerns:

"How do I design my resources?" is an important question to me; "how do I design my URLs?" is a consideration in two areas:

URLs that users will see should not be too ugly and meaningful if possible; if you want cookies to be sent in requests to some resource but not others, you'll want to structure your paths and cookie paths.

If JRandomUser wants to look at his own profile and you want the URL to be prettier than foo.com/user/JRandomUser or foo.com/user/(JRandom's numeric user id here), you could make a separate URL just for a user to look at their own information:

GET foo.com/profile /*examines cookies to figure out who * is logged in (SomeUser) and then * displays the same response as a * GET to foo.com/users/SomeUser. */

I would claim ignorance much more readily than wisdom on this subject, but here are a few resource design considerations:

  1. Consumer: which resources are meant to be viewed directly in a browser, loaded via XHR, or accessed by some other kind of client?
  2. Access / identity: does the response depend on cookies or referrers?
Improve this answer

3 Comments

Great answer, thanks! If I was going to implement your separate URL suggestion (GET foo.com/profile/) would that be part of, as momo suggested, the presentation layer? In other words, what exactly should that GET request return? A web page or some JSON?
Ah, I think I see now. Momo's answer really cleared things up. So a RESTful API is constructed to allow multiple platforms to GET, POST, PUT, and DELETE resources. A website is just another platform accessing the API. In other words, website URL design is completely different than RESTful API design. Please tell me if I'm still wrong haha.
Yes, make your REST API one set of URLs and your website a different set. Then your website URL should give you back appropriate HTML+Javascript so that the page will make appropriate XmlHttpRequests to your API URLs to act as a client.
24

I am going to simply speak from my experience integrating various REST Web Services for my clients, whether it is used for mobile apps or for server to server communication as well as building REST API for others. Here are few observations that I have gathered from other people's REST API as well as those that we built ourselves:

  • When we say API, it normally refers to set of programming interface and not necessary the presentation layer. REST is also data centric and not presentation driven. That said most REST return data in the form of JSON or XML and rarely returning a specific presentation layer. This trait (of returning data and not the direct webpage) given REST ability to do multi-channels delivery. Meaning that the same webservice can be rendered in HTML, iOS, Android or even used as server to server combination.
  • It's very rare to combine both HTML and REST as a URL. By default REST are thoughts as services and not having presentation layer. It is the job for those who consume the webservices to render the data from the services that they call according to what they want. To that point your URL below does not conform with most REST based design that I've encountered thus far (nor the standards such as those who are coming from Facebook or Twitter)
 GET /register // gets the webpage that has the registration form
  • Continuing from previous point, it is also uncommon (and I have not encountered) for REST based service to do redirection such as the ones suggested below: 
 GET /logout // destroys session and redirects to / POST /login // authenticates credentials against database and either redirects home with a new session or redirects back to /login

As REST are designed as services, function such as login and logout are normally returning success/failure result (normally in JSON or XML data format) which then the consumer would interpret. Such interpretation could include the redirection to appropriate webpage as you mentioned

  • In REST, the URL signify the actions that is taken. For that reason, we should remove as much ambiguity as possible. While it is legitimate in your case to have both GET and POST that has the same path (such as /register) that perform different action, such design introduce ambiguity in services provided and may confuse the consumer of your services. For example, the URLs such as the one that you introduce below are not ideal for REST based services
 GET /register // gets the webpage that has the registration form POST /register // records the entered information into database as a new /user/xxx

Those are some points from what I have dealt with. I hope it could provide some insights for you.

Now as far for implementation of your REST, these are the typical implementation that I have encountered:

  •  GET /logout

    Execute logout in the backend and return JSON for denoting the success/failure of the operation

  •  POST /login

    Submit credentials to the backend. Return success/failure. If successful, normally it will also return the session token as well as the profile information. 

  •  POST /register

    Submit registration to the backend. Return success/failure. If successful, normally treated the same as successful login or you could choose to make registration as a distinct service

  •  GET /user/xxx

    Get user profile and return JSON data format for the user's profile

  •  POST /user/xxx // renamed to POST /updateUser/xxx

    Post updated profile information as JSON format and update the information in the backend. Return success/failure to the caller

Improve this answer

4 Comments

Yes, if you are integrating your REST API with HTML based app (via Javascript and AJAX), you will tremendous benefits as JSON is parsed natively by Javascript. In Android/Java, JSON is easier and more straightforward to parse as well compared to XML.
GET /logout is dangerous. GET should be idempotent. Also browsers like to prefetch <a> hrefs, which will log you out!
you have said nothing about nouns vs verbs being used in your endpoint names, POST register is a verb, is that acceptable?
@PirateApp I was just over the same situation and in my opinion the registration as POST request should not be on /register but on /users. Just use CRUD (Create Read Update Delete) on your resources as intended
6

I believe this is a RESTful approach to authentication. For LogIn you use HttpPut. This HTTP method can be used for creation when the key is provided, and repeated calls are idempotent. For LogOff, you specify the same path under the HttpDelete method. No verbs utilized. Proper collection pluralization. The HTTP methods support the purpose.

[HttpPut] [Route("sessions/current")] public IActionResult LogIn(LogInModel model) { ... } [HttpDelete] [Route("sessions/current")] public IActionResult LogOff() { ... }

If desired you could substitute current for active.

Improve this answer

Comments

1

I would recommend using a user account URL similar to twitter where the user's account URL would be something like foo.com/myUserName just like you can get to my twitter account with the URL https://twitter.com/joelbyler

I disagree about logout requiring a POST. As part of your API, if you are going to maintain a session, then a session id in the form of a UUID might be something that can be used to keep track of a user and confirm that the action being taken is authorized. Then even a GET can pass along the session id to the resource.

In short I would recommend that you keep it simple, URLs should be short an memorable.

Improve this answer

2 Comments

The question is about API resources. Your answer is about the presentation layer.
Thou shalt not follow you
0

ReST API itself stands for Representational State Transfer, in which you can you're transferring the resource's state to and fro from your database.

So each verb should be allocated for a resource, whereas in /user/login might not seem to be the correct example to define login to be a resource, wherein user is the actual resource.

Here is what I follow, that might make some sense.

POST /user {userObject} -> To create user resource, i.e, Signup. POST /user/:username {password: `${user_password}`} -> To identify the user by the username and authenticate using the password, i.e, Login. GET /user -> To list all users from your table/collection GET /user/:id -> To get details of a particular user (:id can be replaced with :username, or :email or the primary key you have setup for the user.) PUT /user/:id -> To Update the user object. DELETE /user/:id -> To delete the user object.

The above format is as follows: [HTTP Verb] /resource-path {body(if required*)}.

Whereas for logout, again the state comes into play where you are not transporting the session when logging in, instead a JWT/AccessToken, which is a client-side authorization mechanism, which you store at frontend as local-storage, which just needs to be deleted if not expired when logging out.

You won't have a logout path, that needs to be requested on your API, instead get's handled by expiry time or deleted at frontend only.

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.