How to configure these REST API Resources [closed]

Question

Closed. This question needs details or clarity. It is not currently accepting answers.

---

Want to improve this question? Add details and clarify the problem by editing this post.

Closed 6 years ago.

Improve this question

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.

Answer 1

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.