graphql / graphql/graphql-over-http

General HTTP guidance improvements

Open
#149 6 comments 0 reactions 0 assignees View on GitHub
question
Dominant language
JavaScript
Stars
427
Forks
70
Avg merge
1m
Merged PRs (30d)
5

Description

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

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.