REST: missing metadata in most rest responses

Support
#1

Hi

in other REST frameworks (or DIY solutions I have always built) queries that return a list of entities always contains some metadata in the root JSON representation, like so from Spring DATA Rest typical response (this is from my Typescript code, just to describe the shape of the response):

export interface SdrFindResult {
    _embedded: any;  // this has the dynamic shape `_embedded: { "plural_entity_name": T[] }`
    _links?: any;
    page: {
        size: number,
        totalElements: number,
        totalPages: number,
        number: number
    };
}

here you see that the actual array of entities is contained under the _embedded node, whilst the page one contains pagination metadata.
Apart from the pagination metadata, there could be other metadata info that could be useful for REST clients, and that’s the reason why I never use an array at the root of the response. And that’s a typical pattern that is followed by pretty much every major REST lib/framework out there.

I know this is a breaking change, but please consider changing your mind around this, and start returning something like

{
  entities: [ ... ],
  page: { ... }
}

Now, to work properly with pagination, I need to do a separate call to /count endpoint just to know the total number of records. I expect to have this returned as part of my pagination metadata.

Thanks,
Paolo

1 Like
#3

Hi Paolo,

you are probably right, we’ll definitely think about returning an object instead of array and will try to find the less painful way to introduce this approach. The issue: https://youtrack.cuba-platform.com/issue/PL-9964

Thanks for the idea.

As for the count, you don’t have to call to the /count endpoint. You can just add the returnCount attribute to the request, and the count will be returned in the X-Total-Count response header (see Swagger docs here. Maybe it’s not too convenient, but at least it works.

#4

Thanks @gorbunkov, the X-Total-Count will do the trick for now.

I was looking at an old Swagger doc, this URL: Swagger UI, while your link points to Swagger UI
The former points to an old version of the API specs, and it could be misleading… even the footer with the API version says 6.3 in both pages, but the latter is clearly more up to date.

if you can, please make the former address point to the latest version of the specs (that is, 6.6).

Thanks for your support,
Paolo

#5

As a side note, since I started writing APIs with Hypermedia Controls (Level 3 of Richardson Maturity Model), I can’t easily consume APIs that doesn’t expose meaningful metadata.
I was thinking of writing an experimental (alternative) rest API in CUBA based on JSONAPI specs (http://jsonapi.org/).
After years of experimenting with different hypermedia implementations, JSONAPI resulted in the more pain-less, complete and malleable solution.
There are plenty of ready-made libraries to serialize and deserialize JSONAPI documents (Java and JS are well covered), and CUBA metadata gives 100% coverage of the data needed to build the responses.

A client consuming this hypermedia documents could easily implement automated workflows.
You could also support plain old JSON and JSONAPI at the same time, by adding a top level request router that dispatches requests differently (so even different endpoints and URL structure), based on the Content-Type header.

I don’t know when I’ll have some spare time to start experimenting with this, but I’d like to know your opinion on this matter.

Bye,
Paolo

#6

Swagger UI is the latest one for 6.6
The wrong API number there is fixed now