CODEWITHSUNDEEP
restrestful-urlrestful-architecture
Jeremy
Jeremy

Reputation: 1073

RESTful API subresource pattern

In designing a RESTful API, the following call gives us basic information on user 123 (first name, last name, etc):

/api/users/123

We have a lot of information on users so we make additional calls to get subresources on a user like their cart:

/api/users/123/cart

For an admin page we would like to see all the cart information for all the users. A big table listing each user and some details about their cart. Obviously we don't want to make a separate API call for each user (tons of requests). How would this be done using RESTful API patterns?

/api/carts/users came to mind but then you'd in theory have 2 ways to get a specific user's cart by going /api/carts/users/123.

Upvotes: 0

Views: 1911

Answers (2)

Jeremy
Jeremy

Reputation: 1073

For some reason I was under the assumption that having 2 URIs to the same resource was a bad thing. In my situation /api/users/123/cart and /api/carts/users/123 would return the same data. Through more research I've learned from countless sources that it's acceptable to have multiple URIs to the same resource if it makes sense to the end user.

In my case I probably wont expose /api/carts/users/123, but I'm planning on using /api/carts/users with some query parameters to return a subset of carts in the system. Similarly, I'm going to have /api/carts/orgs to search org carts.

A really good site I found with examples and clear explanations was the REST API Tutorial. I hope this helps others with planning their API URIs.

Upvotes: 0

Ned Rockson
Ned Rockson

Reputation: 1175

This is generally solved by adding a deref capability to your REST server. Assuming the response from your user looks like:

{
  ...
  cartId: "12345",
  ...
}

you could add a simple dereference by passing in the query string "&deref=cart" (or however you setup your syntax.)

This still leaves the problem of making a request per user. I'd posit there are two ways to generally do this. The first would be with a multiget type of resource (see [1] for an example). The problem with this approach is you must know all of the IDs and handle paging yourself. The second (which I believe is better) is to implement an index endpoint to your user resource. Indexing allows you to query a resource (generally via a query string such as firstName=X or whatever else you want to sort on.) Then you should implement basic paging so you're not passing around massive amounts of data. There are tons of examples of paging, but the simplest would be to specify a number (count=20) a start token (since=X) and a sort order (sort=-createdAt).

These implementations allow you to then ask for all users and their carts by iterating on the index endpoint. You might find this helpful as a starting point for paging [2].

[1] - How to construct a REST API that takes an array of id's for the resources

[2] - Pagination in a REST web application

Upvotes: 1

Related Questions