REST API Filtered GET with different Response Structure

Question

I am designing a REST API that has the following endpoint

GET /foo: returns list of foos where foo is a complex object

So far so clear, now I want to add another endpoint that returns only ids of foo and only for certain foos that match a predefined condition, let's say only foos that have the property marked = true. I am wondering how I should design the API to adhere to best practices. My ideas so far:

GET /foo/marked
GET /markedFoo

What would be the right choice considering best practices?

Have you considered query parameters? https://stackoverflow.com/questions/4024271/rest-api-best-practices-where-to-put-parameters — Tim, Sep 18 '19 at 13:51
What I don't like about query parameters here is that the new method should only return id's whereas the normal GET /foo returns objects — user2074945, Sep 18 '19 at 13:53

VoiceOfUnreason · Accepted Answer · 2019-09-18T17:32:38.317

What would be the right choice considering best practices?

REST doesn't care what spelling you use for your resource identifiers.

GET /foo/marked
GET /foo?marked
GET /foo/marked=true
GET /foo?marked=true
GET /markedFoo
GET /marked/Foo
GET /marked?Foo

Those are all fine.

In cases where you are expecting the client to provide some information -- the list of columns it wants to see, for instance -- then you would want to choose a URI spelling recipe consistent with some URI Template. Ideally, you would choose one of the template variations where your clients will have an easy time finding a matching library implementation.

If your clients are going to be navigating your API by consuming HTML representations, then you should consider URI spellings that are consistent with form processing (ie, planning for application/x-www-form-urlencoded representations of the template arguments to be included in the query string).

In an API where you intend to use relative references, then you'll want to think carefully about the identifier hierarchy, so that you can use dot segments to describe the spelling of one URI relative to another.

Beyond that, it's mostly bike shedding.

I suggest that you treat URI spelling like you would the spelling of a variable name: from the space of all spellings that can work in the use cases you have in mind, pick one that is consistent with the rest of your API and has a decent balance between readability and complexity.

What I don't like about query parameters here is that the new method should only return id's whereas the normal GET /foo returns objects

A thing to keep in mind is that, as far as REST is concerned, different resource identifiers mean different resources. /foo and /foo?1 are not related to each other any more than /c818d995-7565-4a5f-8ecf-49da9bf020c0 is related to /c818d995-7565-4a5f-8ecf-49da9bf020c1.

But if you think human beings are going to get confused, you are probably right. So choose a spelling where the differences aren't subtle.

REST API Filtered GET with different Response Structure

1 Answers1