Skip to content

Commit

Permalink
Added two sections explaining, which HTTP request methods are allowed…
Browse files Browse the repository at this point in the history 
… in combination with the Content-Warning field and the embedded-warning
  • Loading branch information
@andrecedik
andrecedik committed May 14, 2020
1 parent 57e44fc commit a419ba8
Showing 1 changed file with 16 additions and 0 deletions.
16 changes: 16 additions & 0 deletions http-warning/draft-cedik-http-warning-02.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,11 @@ Content-Warning = sh-list
<t>
Intermediaries of a response are not allowed to modify existing Content-Warning fields, but can add additional entries if warnings are produced while they are handling a response.
</t>
<section anchor="http-request-methods" title="HTTP request methods">
<t>
The Content-Warning Field is not tied to any specific HTTP request method, although specific values MAY only be used with a single or a subset of methods. The information as to which HTTP request methods are support for a single Content-Warning Type MUST be defined in the definition of the Content-Warning Type.
</t>
</section>
</section>
<section anchor="embedded-warning" title='The "embedded-warning" Content-Warning Type'>
<t>
Expand All @@ -110,6 +115,17 @@ Content-Warning = sh-list
<figure><artwork><![CDATA[
Content-Warning: "embedded-warning"; 1590190500
]]></artwork></figure>
<section anchor="allowed-http-request-methods-for-embedded-warning" title="Allowed HTTP request methods for embedded-warning">
<t>
The embedded-warning Content-Warning Type infers, that there is more information in the responses body. Therefore all HTTP request methods that MAY have content in their body MAY also return embedded warnings.
</t>
<t>
HTTP request methods that do not return a body in their response SHOULD NOT return the embedded-warning Content-Warning Type.
</t>
<t>
The HTTP request method HEAD is an exception since it is allowed to return headers that are meant for being returned when sending a GET request. Therefore it MAY return the embedded-warning Content-Warning Type, although the body will be empty.

This comment has been minimized.

Sign in to view

Copy link
@ioggstream

ioggstream May 14, 2020

Contributor

Can you clarify with the following example?

I PUT a book and receive a content-warning

Request:

PUT /books/1

{"title": "ABC", "author": "Smith"}

Response:

200 Ok
content-warning: embedded-warning

{"title": "ABC", "author": "Smith", "warnings": [{ "title": "title  too short"}]}

I made a subsequent request

GET /books/123

Then

Will the second response contain a warnings section and a content-warning header?

This comment has been minimized.

Sign in to view

Copy link
@andrecedik

andrecedik May 15, 2020

Author Collaborator

Hi, just to clarify - the subsequent request could be

GET /books/1

or, to catch the theme of the I-D text above your comment, could be this:

HEAD /books/1

Both of them could have the content-warning field and warnings in the body. While you'd return the same response like the one above, when using GET you'd probably only return the warnings when using HEAD.

Normally I would say it should not come to this since after validating the first request, the server should return a 400 - Bad Request and not save the data. But that's just my point of view. The use case could be that the title is not that important for service and this is just a warning to inform the client about the fact.

So it probably is up to the provider of the service to define if they want to inform the client about data that should be corrected. So I would say that subsequent requests could return the same warnings to let a client display them to a user sitting in front of a UI.

This comment has been minimized.

Sign in to view

Copy link
@ioggstream

ioggstream May 15, 2020

Contributor

Both of them could have the content-warning field and warnings in the body

afaik HEAD will not return a payload body, so cannot return warnings in the body.

IMHO the described behavior is consistent only if warnings is part of the actual representation and always returned by subsequent GETs.

This comment has been minimized.

Sign in to view

Copy link
@andrecedik

andrecedik Jun 5, 2020 •
edited
Loading

Author Collaborator

Ohh sorry. I just realised, that my comment was misleading. What I meant was, when using HEAD a client can receive a content-warning field in the response. The type won't be embedded-warning since this would imply that a warning-entry can be found in the body.

That is why in line 123 the spec says

HTTP request methods that do not return a body in their response SHOULD NOT return the embedded-warning

This comment has been minimized.

Sign in to view

Copy link
@ioggstream

ioggstream Jun 5, 2020 •
edited
Loading

Contributor

I'll try to put that differently. Do you think Content-Warning is more like a:

Once defined that, let's align the behavior to one of them.

I won't tie the spec to a specific method (eg. HEAD) as methods can be added by other specs (eg. PATCH). Referencing a class of header simplifies the creation of consistent behaviors.

This comment has been minimized.

Sign in to view

Copy link
@andrecedik

andrecedik Jun 24, 2020

Author Collaborator

Phew - well I'd say it is more representation data than payload header, since a warning is supposed to describe a case where the server returns information (in the response body) about something the recipient should be informed about - in our case a warning. More information about what has happened can be found in the body, making it representation metadata.

But, I'd also love to hear @dret thoughts on this topic.
</t>
</section>
</section>
<section anchor="warning-format" title="JSON Warning Format">
<t>
Expand Down

0 comments on commit a419ba8

Please sign in to comment.