REST GET mehod: Can return a list of enriched resources?

Question

I have a doubt when I'm designing a REST API.

Consider I have a Resource "Customer" with two elements in my server, like this:

[
   {
      name : "Mary",
      description : "An imaginary woman very tall."
   },
   {
      name : "John",
      description : "Just a guy."    
   }
]

And I want to make an endpoint, that will accept a GET request with a query. The query will provide a parameter with a value that will make an algorithm count how many occurrences for this text are there in all of its parameters.

So if we throw this request:

GET {baseURL}/customers?letters=ry

I should get something like

[
       {
          name : "Mary",
          description : "An imaginary woman very tall.",
          count : 3
       },
       {
          name : "John",
          description : "Just a guy.",
          count : 0
       }
    ]

Count parameter can not be included in the resource scheme as will depend on the value provided in the query, so the response objects have to be enriched.

I'm not getting a list of my resource but a modified resource.

Although it keeps the idempotent condition for GET Method, I see it escapes from the REST architecture concept (even the REST beyond CRUD).

Is it still a valid endpoint in a RESTful API? or should I create something like a new resource called "ratedCustomer"?

Answer 1

REST GET mehod: Can return a list of enriched resources?

TL;DR: yes.

---

Longer answer...

A successful GET request returns a representation of a single resource, identified by the request-target.

The fact that the information used to create the representation of the resource comes from multiple entities in your domain model, or multiple rows in your database, or from reports produced by other services... these are all implementation details. The HTTP transfer of documents over a network application doesn't care.

That also means that we can have multiple resources that include the same information in their representations. Think "pages in wikipedia" that duplicate each others' information.

Resource identifiers on the web are semantically opaque. All three of these identifiers are understood to be different resources

/A
/A?enriched
/B

We human beings looking at these identifiers might expect /A?enriched to be semantically closer to /A than /B, but the machines don't make that assumption.

It's perfectly reasonable for /A?enriched to produce representations using a different schema, or even a different content-type (as far as the HTTP application is concerned, it's perfectly reasonable that /A be an HTML document and /A?enriched be an image).

Because the machines don't care, you've got additional degrees of freedom in how you design both you resources and your resource identifiers, which you can use to enjoy additional benefits, including designing a model that's easy to implement, or easy to document, or easy to interface with, or easy to monitor, or ....

Design is what we do to get more of what we want than we would get by just doing it.