HttpClient documentation confusing ("response body as a JSON object") about overload #14 / #15 of multiple methods (request, get, post)

[Chealer]

Description

As HttpClient's documentation shows, its methods provide numerous variants, which return various results. The results depend on what the HTTP requests return. When a request returns JSON, the call will provide an object corresponding to the object represented by the returned JSON string.

For example, the specification of "overload #14" of get() ends with:

Returns Observable<Object>: An Observable of the response body as a JSON object.

To my knowledge, there is no such thing as "a JSON object". What the Observable may provide is a [JavaScript] object corresponding to the returned JSON string.

This also affects overload #14 of delete(), head() overload #14, options() overload #14, patch() overload #14, post() overload #14, put() overload #14 and request() overload #15.

What is the affected URL?

https://angular.io/api/common/http/HttpClient

Please provide the steps to reproduce the issue

This does not report a behavioral bug.

Please provide the expected behavior vs the actual behavior you encountered

This does not report a behavioral bug.

Please provide a screenshot if possible

No response

Please provide the exception or error you saw

This does not report a behavioral bug.

Is this a browser-specific issue? If so, please specify the device, browser, and version.

No

[pkozlowski-opensource]

Would the "JSON value" terminology (instead of "JSON object") work for you? Up to opening a PR?

[makadiyaparth]

JSON is a format. I would say "JSON" instead of "JSON object". Would that clear the confusion?

[Chealer]

@pkozlowski-opensource I am not sure what you mean by "a PR", but I don't think that would work. I find "JSON value" maybe even more unclear than "JSON object".

@makadiyaparth you are right that JSON is a format. However, if the methods return an object, their documentation needs to specify which object is returned. A starting point would be to specify the type of the returned object.

[ashide2729]

I agree with @Chealer, looks like a general mistake among devs, read here I suggest we change it to Object according to the explanation given in the link above also, there are other places as well where I can see 'JSON object' mentioned on the page(60 matches found using search) which might need fixing

btw I tried to find the text for fixing but looks like the whole content is stored in backend side, is that the case or am I missing something? cc: @makadiyaparth @pkozlowski-opensource

[Chealer]

Thank you for the interesting research @ashide2729 While changing to "object" would be exact and better, it would be much better to use a phrasing which at least partly specifies the returned object, like the one I offered.

[giovnzcr]

@AndrewKushnir Can I get assigned to this one ?

[angular-automatic-lock-bot[bot]]

This issue has been automatically locked due to inactivity. Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}