Update Javadoc of `retrieve` in `GraphQlClient` for decoding full data

[kitkars]

Hi Spring Team,

It is a request / question.

Can you provide an additional overloaded method .retrieve() in the GraphQlClient's RequestSpec if the users want to access the whole data response?

We do have some work around as shown here but it would be better to have it part of RequestSpec itself.
.retrieve("")
or
execute().map(...)

[rstoyanchev]

Generally, execute is for access to the full response and you can can convert the entire data from there:

.execute().map(response -> response.toEntity(...))

We could consider retrieve() without any arguments but it seems like most often, you'll have at least a top-level path to go navigate? Could you clarify on the scenario, does the data contain multiple keys, and what would you decode to?

[kitkars]

Thanks @rstoyanchev

Is it not normal to have multiple keys inside the data object? For ex: I ask for a book by id and along with some recommendations. (may be a bad example.) and I might want to map it to a BookWithRecommendationsDto. Others might not be interested in the recommendations and might be interested only in the book object.

{
    "data": {
        "book": {..},
        "recommendations": [
            { .. },
            { .. }
        ]
    }
}

It is not a blocker. Currently I could use .retrieve(""). But as you see it makes the code super ugly.
So adding a default retrieve() in the interface would be nice to have as we have in the WebClient.
If you have other plans to make it better, that would be great too. I can go with execute as well.

[rstoyanchev]

Multiple keys is no problem. This is what you can do right now:

.execute().map(response -> response.toEntity(BookWithRecommendationsDto.class))

I'll schedule this to add retrieve() as a shortcut for the above.

[kitkars]

Thank you sir, I appreciate it.

[rstoyanchev]

On closer look, since the full data cannot be a List, the toEntityList methods don't make sense and would need to be implemented by raising an error. Even the Javadoc of retrieve is specifically positioned as a shortcut for a specific field. I'm afraid you'll have to rely on the version I suggested above in #434 (comment). I did update the Javadoc on retrieve and retrieveSubscription to make a note of this case so it's easy to find.