RESTful design for an endpoint to filter and return only the latest created resource

问题

I have an application where a user can create many subresources for a given one. Let's say the endpoint looks like this:

POST /main-resources/{id}/sub-resources

The subresource contains a period of time limited by dates as part of the body, something like:

{
    "startDate": "2018-10-10",
    "endDate": "2018-12-12"
}

They are also consider value objects. In terms of the application, they don't have an id (even though they are backup by a SQL database so effectively they have one) as it doesn't make sense to search for a subresource without going through the main one in this case.

Now, I would like to create an endpoint that allows the user to find the subresources for a given main resource but it has to return just the latest one created which period of time contains a given date. Something like the following:

GET /main-resources/{id}/sub-resources/latest?date=2018-11-11

My problem here is that latest seems like a filter to me. latest can return different values each time it is called depending on whether the user has created new subresources which by my understanding it's not RESTful. Instead of the previous endpoint, I think it should look more like:

GET /main-resources/{id}/sub-resources?latest=true&date=2018-11-11

or

GET /main-resources/{id}/sub-resources?limit=1&date=2018-11-11&order=desc

which gives more options but won't actually be needed in my use case.

Doing it this way, the user would normally expect one result but that would close the door to other types of filtering like filtering just by the date.

So basically I have the option to create an endpoint that includes latest as a path variable, which would return a single element, or use it as a parameter which would normally have to return a list of elements even though this filter specifies the user only wants one, making it a little bit more annoying for the client.

Is there any other alternative?

回答1:

My problem here is that latest seems like a filter to me. latest can return different values each time it is called depending on whether the user has created new subresources which by my understanding it's not RESTful.

The latest identifier seems to be just fine. See the following quote from the chapter 5 of Fielding's dissertation, where the REST architectural style is defined:

Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time. The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another.

For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently. A similar example from software engineering is the separate identification of a version-controlled source code file when referring to the "latest revision", "revision number 1.2.7", or "revision included with the Orange release."

来源：https://stackoverflow.com/questions/54903587/restful-design-for-an-endpoint-to-filter-and-return-only-the-latest-created-reso