HTTP status codes and responses

[adeinega]

No description provided.

[netlify]

Deploy preview for gnap-core-protocol-editors-draft ready!

Built without sensitive environment variables with commit 7db9ff3

https://deploy-preview-206--gnap-core-protocol-editors-draft.netlify.app

[jricher]

In general I think we're holding off on defining error codes until the core protocol is more solid, but thanks for this! See #79 for the issue tracking this major hole in the spec.

[adeinega]

I was a bit surprised that the draft says nothing about any HTTP status codes in case of errors. 400 (and 401) are the most important ones in my opinion. These changes just a little step in this direction... without defining detailed error codes.

[jricher]

Not accepted, will address both error codes and response codes in a more comprehensive edit in the future.

[Denisthemalice]

I concur with adeinega when he says:

I was a bit surprised that the draft says nothing about any HTTP status codes in case of errors.

Common error codes should be mentioned in the draft, in particular 401, 403 and 405.

This will augment the size of the document of about one page, but it is worth to do it, in particular
to make the difference between an authentication error (401) and an authorization error (403).

[jricher]

The editors have agreed (and stated above) that error codes need to be added to the draft. However, that should be done in a more comprehensive manner than what is described in this PR and so we will address it in a future update. Nobody is saying that we should not add error codes, so please don't imply otherwise.

[adeinega]

GNAP is closely tied with The Hypertext Transfer Protocol (HTTP) and, as a starting point, it is worth specifying that

1. 200 (OK) indicates that the request succeeded
2. 400 (BAD REQUEST) indicates that the request hasn't succeeded

before we go any further and identify detailed error codes and this is exactly what I suggested doing in this PR. Although, those are pretty minor changes and if the editors / WG decide to not include them, I'm OK.

This specification could mention lots of other nuances in this area... such as redirect policies (if there are any) for the grant, introspect, continuation, as well as other endpoints. The use and presence of standard response headers like Date, Content-Length and Content-Encoding, an HTTP 429 (Too Many Requests) status code as a way to control the rate of requests, the HTTP Retry-After header, and so forth. This list goes on and on.