General HTTP guidance improvements

Open
  • Is something wrong?
#149 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
graphql
Domain
api, documentation

Research direction

Review the GraphQL over HTTP specification and the issue's proposed HTTP guidance, authentication, file handling, idempotency, error-code, and directive topics. First determine which proposals are in scope and whether the reference implementation must change. Done means an agreed scope is reflected in the specification and any corresponding reference-implementation coverage.

Written by the indexing model from the issue text.

Description

question

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

Dominant language
JavaScript
Stars
428
Forks
70
Avg merge
11m
Merged PRs (30d)
4

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from graphql/graphql-over-http

All issues in graphql/graphql-over-http

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.