Response.json()

[ricea]

Braw mornin' TAG!

I'm requesting a TAG review of Response.json().

Response.json(body) is a static method used to construct a Response object from the JSON serialisation of "body". It does what you would want new Response(body) to do if that was not ambiguous.

• Explainer¹ (minimally containing user needs and example code): https://github.com/ricea/response-json-explainer/blob/main/explainer.md
• Specification URL: https://fetch.spec.whatwg.org/#dom-response-json
• Tests: https://wpt.fyi/results/fetch/api/response/response-static-json.any.html
• User research: N/A
• Security and Privacy self-review²: https://docs.google.com/document/d/1GicefRvYuPrw2tsb8jdjileomK7TW7xYLkP37oz1FbQ/edit
• GitHub repo (if you prefer feedback filed there): https://github.com/whatwg/fetch
• Primary contacts (and their relationship to the specification):
  • Adam Rice (ricea), Google, proposing to ship this feature in Chromium.
  • Anne van Kesteren (annevk), Apple, specification change reviewer.
  • Luca Casonato (lucacasonato), Deno, specification change author.
• Organization(s)/project(s) driving the specification: Deno, Mozilla
• Key pieces of existing multi-stakeholder review or discussion of this specification: Proposal: Response.json helper whatwg/fetch#1389
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): feat(ext/web): implement static Response.json denoland/deno#14566 feat: add Response.json nodejs/undici#1452

Further details:

• [ X ] I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: As we already have an implementation ready to land, we would like to ship this soon in Chromium.
• The group where the work on this specification is currently being done: WHATWG
• The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): WHATWG
• Major unresolved issues with or opposition to this specification: None
• This work is being funded by: Google is paying me to write this document. The implementation in Chromium was done by a third-party, as was the specification work.

You should also know that...

It is a very small feature.

We'd prefer the TAG provide feedback as (please delete all but the desired option):

💬 leave review feedback as a comment in this issue and @-notify ricea, annevk, lucacasonato

¹ We require an explainer to give the relevant context for the spec review, even if the spec has some background information. For background, see our explanation of how to write a good explainer. We recommend the explainer to be in Markdown.

² A Security and Privacy questionnaire helps us understand potential security and privacy issues and mitigations for your design, and can save us asking redundant questions. See https://www.w3.org/TR/security-privacy-questionnaire/.

[torgo]

Any chance you could publish the explainer and questionnaire responses in markdown along side of the spec please?

[ricea]

I've created Markdown versions at https://github.com/ricea/response-json-explainer.

@annevk how would you feel about including them in the fetch repository?

[annevk]

I could see adding an example to the standard. WHATWG standards are expected to be self-contained documents so I wouldn't really want to add separate markdown files that also need to be consulted/maintained.

[LeaVerou]

Hi @ricea,

We took a look at this today during a breakout. While the functionality seems worthwhile, we are concerned that it might be confusing that there is an instance method and a static method with the same name that do exactly opposite things. This is also acknowledged in the explainer, but as a benefit:

This is symmetric with the Response.prototype.json() method which converts back the other way.

We are also unsure if it's a good idea to have a factory method whose naming does not indicate that it's a factory method.

What are your thoughts on this? What alternative names have you considered?

[LeaVerou]

Hi again. We looked at this again during a breakout today.

We still think that it's confusing if any static method could be a factory method, and we believe there is value in making this obvious with a naming convention. As an example, we explored ideas such as Response.from(value, options) with a dictionary argument whose type defaults to "json", which would be equally concise.

However, we see that there is precedent in having factory methods in this API whose names are simple nouns (Response.error(), Response.redirect()), and we think internal consistency within the API is more important than external consistency with the rest of the Web Platform, so we will go ahead and close this.

[ricea]

Thank you for the feedback. I like the idea of Response.from() but since most types can simply be passed to the constructor, it might turn out to be a misleadingly general name.