Retrieving entities with related entities using REST API

we're using REST API for communication between our client (UI) and server. We have implemented paged GET-ting of resources of one type, for example:

GET http://../cars?page-size=10,start-index=3

will return you maximum 10 cars starting from car 21 (i.e. 3rd page of 10 cars).

We want to add a possibility to ret开发者_Go百科urn entities with related entities, in which there can be many related entities (possibly tens or hundreds) to one main entity. Currently this is done using 2 requests: for example first GET on cars, then GET on doors using previously fetched car IDs as a parameter:

GET http://../doors?car-ids=1,2,5,7,...

However, in order to minimize the number of requests, we would like to use 1 request to return the required information. The following questions arise:

1. How should paging be integrated with such a functionality? Should related entities number (doors) be limited to the page size of the main entity (car)? Maybe we should separate the page size of the main entity and related entities (e.g. 10 cars, 2 doors maximum for each car)?
2. How do we make sure the solution is scalable in the server-side in terms of memory usage? Currently we use JAXB to serialize entities to XML. Should we consider using streaming XML techniques (STAX) to prevent loading all of the entities to memory?

Thanks a lot.

Concerning question 1:

I'd create a snapshot resource, that returns the resource entity itself as well as all related entities: GET /car/{car-id}/snapshot Knowing that this will return a snapshot with a possibly large response entity, it's okay to return a rather large, non-paginated list of the subentities (i.e. doors). You might however throttle the number of requests clients can dispatch against this rahter costly snapshot resource. You can even provide a resource for batch requests, such as /cars/snapshots, where you can POSTmultiple car IDs and retrieve multiple snapshots at once (in this case, I'd limit the number of IDs to be included in the batch request as well).

On the other hand, I' create a paginated list with subentities: GET /car/{car-id}/doors (303 to first page) and GET /car/{car-id}/door/{door-id as cursor} for each page.

This will allow clients to choose the reprensation that is most appropriate for their usage, either iterate through all doors listed, or fetch the complete snapshot of the car, if the clients needs it anyway.

I think that the REST issue here is less important than the OO analysis

The resource here is the Car. The number of doors is an attribute so model your system around the Car resource with some sensible way to express your queries.

The least surprising (and therefore probably the best) approach is to add to the existing query of cars. Taking your example:

GET http://../cars?doors=2+,page-size=10,start-index=3

Remember that the key aspect of REST is that every resource has a URL. REST says nothing about how the URL is formed so don't worry about the RAILs-style nested resources.In Fielding's own words ...

What matters is that every important resource have a URI, therein allowing representations of that resource to be obtained using GET.