0

I'm still in the design phase of my REST API, and I'm a bit stuck on how to configure the resources. The API will be consumed by mobile devices (Android, iOS, and Windows). Communication through HTTPS.

These are the features the API will support:

  1. View a list of previous reservations
  2. View a previous reservation
  3. Create a new reservation
  4. Create a new anonymous reservation

I was thinking of naming my resources as following:

  1. api/users/{id}/reservations (GET)
  2. api/users/{id}/reservations/{id} (GET)
  3. api/users/{id}/reservations (POST)
  4. api/users/0/reservations (POST)

I'm not sure if the resource for 4 is a good design?

Also 1, 2, 3 require a user to have an account and be authenticated. Authentication will be done using an access-token. This means the user has to log in every X period.

Is it bad to store the user id on the device so it is able to perform requests where the user id is required? Or should I just remove the /users/ part from the resource and have the server decide based on the access-token which user is trying to perform a specific action?

The REST API will be built using ASP.NET MVC4.

Improve this question

1 Answer 1

Reset to default
2

What is your application about? Reservations or users?

The fact that reservations can be made anonymously is a dead give away that your application is about reservations and that users are "just" a way to make it easier for return visitors to make a reservation (not having to fill in their details again).

As reservations can obviously exist without a user, there should be no need to fake a user when posting a reservation.

All this leads to the inevitable conclusion that reservations should come first. And that your URI's should reflect that.

Posting an anonymous reservation is then as easy as pie:

  • POST to /api/reservations

And posting a reservation by a specific user can also be handled by this URI. The user id of the logged in user id is already known by other means and it should not be necessary to repeat it in the URI. How would you like it when I as a logged in user make a reservation using your user id (which could be easily gleaned from the URI's) and thus have your credit card charged?

Putting reservations first when it comes to retrieving them leads to URI's like these:

  • GET to /api/reservations

for all reservations by the logged in user, and for reservations made by a user other than the logged in user, you could have

  • GET to /api/reservations/users/{id}, or
  • GET to /api/reservations?user={id}

Getting reservations made by someone other than the logged in user should probably be a feature restricted to administrators. As such it sounds more like filtering/search.

While using URI scopes to filter is quite acceptable, it does carry the limitation that adding fields on which to filter can become a pain. Using query parameters is a more natural fit for filter criteria, with the added benefit will be a lot easier to extend the number of fields that can be used as filter criteria.

Improve this answer
2
  • /reservations/{reservation_id} would be nice to have for URIs. Then, users is something you wouldn't expect in a collection of ids. In REST it is very acceptable to have multiple URLs to access the same resource. So why not have /users/{user_id}/reservations in addition, so we keep the endpoints "pure"? It can then be used for cases in which the user is central (making, showing, canceling reservations for a user). Say we add invoices later, there'll be /users/{user_id}/reservations and /users/{user_id}/invoices, so /users/{user_id} can be an "index" to help discovery in HATEOAS.
    – Thijs van Dien
    Nov 14, 2013 at 21:09
  • @Thijs Hmm, yes, I didn't go into any other uri's OP's application could support. URI's shouldn't be created just because they are possible or might be needed. They should serve a real business need. For example /users/{user_id}/reservations, could serve the needs of a customer service rep needing to get the reservations of someone they are talking to on the phone. If there is such a need, consider creating that URI, but also consider whether the business need is already served in another way (ie general search). I see no point in creating additional URI's just for the sake of purity.
    – Marjan Venema
    Nov 15, 2013 at 14:45

Not the answer you're looking for? Browse other questions tagged or ask your own question.