Use 203 as the partial status code

[benjie]

See changes for explanation.

Note: this will need testing before we can merge it.

[BoD]

Is there already work around code 294? A quick search didn't yield any results.

[benjie]

Only what I’ve previously proposed, which has been overwritten by this. Just a new status code really. “94” being “PA” for PArtial 🤷‍♂️

[BoD]

Wondering if a specific header could be added (but not sure which one!) instead of re-using a status code with a different meaning.

My only concern is that intermediaries may interpret 203 in unexpected ways.

[phryneas]

(removed, discussed later in the RFC text anyways)

[phryneas]

I'm not sure it needs to be read like that.

Later in section 6.1.1, they keep an open door for extension:

HTTP status codes are extensible. HTTP applications are not required
to understand the meaning of all registered status codes, though such
understanding is obviously desirable. However, applications MUST
understand the class of any status code, as indicated by the first
digit, and treat any unrecognized response as being equivalent to the
x00 status code of that class, with the exception that an
unrecognized response MUST NOT be cached. For example, if an
unrecognized status code of 431 is received by the client, it can
safely assume that there was something wrong with its request and
treat the response as if it had received a 400 status code. In such
cases, user agents SHOULD present to the user the entity returned
with the response, since that entity is likely to include human-
readable information which will explain the unusual status.

Additional status codes that are not part of section 10 are defined in RFC 6585, which officially Updates: 2616.
But new status codes are also defined outside of the scope of 2616, e.g. status code 207 is defined in RFC4918 without any mention of "updating" RFC 2616, it's only referenced in different context there.

So, going by that, we wouldn't necessarily be restricted to the RFC 2616 status codes - but of course, introducing a new one might bring it's own risk.

That said, RFC 4918 reads to me like it only applies to very specific contents types, so maybe 207 with a different content type might actually not provoke a conflict?

A Multi-Status response conveys information about multiple resources
in situations where multiple status codes might be appropriate. The
default Multi-Status response body is a text/xml or application/xml
HTTP entity with a 'multistatus' root element. Further elements
contain 200, 300, 400, and 500 series status codes generated during
the method invocation. 100 series status codes SHOULD NOT be recorded
in a 'response' XML element.

[Shane32]

My thoughts:

203 Non-Authoratative Information

Benefits:

• Proxies, firewalls and clients are unlikely to refuse a document because the code is 203; this would be a normal and expected status code to see, which does not imply any improper behavior.

Cons:

• Name and description do not have any relation to GraphQL partial response
• Proxies may be in use along a HTTP communication path, and may change responses to 203 or consume it. However, for server side logging, it doesn't matter what a proxy does with the status code after it's left the server

206 Partial Content

Benefits:

• Name somewhat matches intended use

Cons:

• Proxies, firewalls or even clients may attempt to validate the content, and (1) seeing no Content-Range response header, or (2) not expecting a partial response, reject the request

207 Multi-Status

Benefits:

• Name and description closely matches intended use
  • Although '207' is used as the overall response status code, the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations.
• The status code is commonly in use and should be supported by proxies and firewalls
• The status code is defined in WebDAV's RFC, layered under HTTP, and not the HTTP protocol itself, much the same way this GraphQL RFC is layered under the HTTP protocol. As such, proxies should be oblivious to the content and pass along the request.

Cons:

• Firewalls may attempt to validate the content type of data returned with a 207 response type (at a minimum), and finding it is not XML, reject the response.

294 Partial Response (or another GraphQL-defined code)

Benefits:

• No overlap with other status codes
  • Logging providers can choose to recognize 294 as a GraphQL-specific response code

Cons:

• Firewalls may reject responses with this unrecognized status code
• Exactly duplicates the purpose of status code 207
• Getting IANA approval for a new officially recognized status code may prove difficult, given the presence of 207

[Shane32]

It should be noted that since most all requests will be HTTPS, the above firewall considerations only apply to application-level firewalls (Secure Web Gateway), as regular firewalls would not have access to the response code.

[Shane32]

I would select 207 because its exact description matches our use case. But first I would prefer to see some testing with commonly used Secure Web Gateways. I wouldn't worry about server-end proxies because the GraphQL server operator would set that up as needed (which may include changing the response code of the GraphQL server to always be 200). And the use of Secure Web Gateways are probably limited to large companies or governments which are likely enough to have a team ready to allow (or disallow) access to specific websites. So testing becomes less important. The only leaves other proxies, such as a cell provider might install to make their network appear faster, which I don't think proxies would be an issue with 207. So I'd go with 207. (Just my two cents.)

203 is probably the "safest" choice....

[Shane32]

Note that 201/202 also are as "safe" of a selection as 203, perhaps moreso. But again, the meaning doesn't carry over to GraphQL's intended use at all.