General HTTP guidance improvements

[jayadeba]

Hi,

I see that the proposed spec is supporting most HTTP status codes. Does this group have any opinion on the following;

1-Providing guidance in the specification to use appropriate HTTP codes, particularly around the HTTP error codes 4XX/5XX to describe the outcome, without being prescriptive about which error code should be used when, would be helpful.

2-Describing how to perform Authentication Authorization for GraphQL requests over HTTP would be helpful (even though AuthN and AuthZ can be outside the scope of this spec, specifying it so and having references to standard API protocols such as OpenId connect/OAuth2 would be useful).

3-Providing some guidance/making statements around File handling (It is ok to specify that this should be done outside the GraphQL request/response handling)

4-Providing some guidance around idempotent mutation operations over HTTP

5-In the reference implementation, covering all HTTP error codes would be helpful for the Implementor (at least the most widely used codes such as 400, 401, 403, 404, 409, 422, 405, 415, 413, 500, 503

Finally coming up with directives to describe HTTP protocol specific metadata in the schema would be helpful. Some example below;

1-Declaring authorization requirements at an Operation level (@AuthPolicy or @authorization directive?)
2-Declaring that a Mutation Operation is idempotent (@idempotent directive?)
3-Declaring the HTTP request and response headers in the schema (@httpRequestHeader and @httpResponseHeader directives?)
4-Declaring the status codes of each Operations (@httpstatuscodes directive?)

Non-HTTP
1-Declare the grouping of API operations by product capability (although not HTTP specific) (@tags directive?)
2-Declaring service level objectives for an operation (@slo directive?)
3-Declaring the unique operation id for each API operation (@operationid directive?)

Happy to discuss these and contribute back. Also happy to share things we did ay PayPal around these.

Thanks,
Jayadeba

[benjie]

I've added this to the 1.0 Release not because we'll address all these points, but because I want to make sure we at least consider them, even if we decide to take no action at this time. We'll probably move this to a later release (or close it) depending on the outcome of these considerations. Thanks for the input @jayadeba 👍