General HTTP guidance improvements #149
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
Activity
[-]Support for 403[/-][+]Support for 403 and other error handling improvements[/+][-]Support for 403 and other error handling improvements[/-][+]General HTTP guidance improvements[/+]benjie commentedon Jul 1, 2022
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 👍
martinbonnin commentedon Aug 11, 2026
Hey @jayadeba. Thanks for sending that list. That's a lot of things! Few feedbacks:
There is now a whole section about it there: https://graphql.github.io/graphql-over-http/draft/#sel-DANNDTAAEVDEQq-Z
The general rule is:
data, return2xxdata, return4xxor5xxas appropriate. The spec gives some recommendations but does not prescribe the exact status codes (just that they are4xxor5xx).That sounds interesting. I'm not aware of anything yet. Could maybe be a best practice?
Did you mean file upload? There is a best practice there: https://graphql.org/learn/file-uploads/
I'm confused. Mutations are typically not idempotent (contrary to queries). Can you ellaborate a bit more?
There is a good bunch covered at https://graphql.github.io/graphql-over-http/draft/#sel-DANNDTAAEVDEQq-Z
See #150. I'm going to recommend to do this in GAPs, which have been done exactly for that purpose.
I know it's been a long time. If you're still around, please feel free to comment here or even open more specific issues for some of the points above, either in this repo or in the GAPs repo.
In the absence of response from you, I'll close this issue as non-actionable.
benjie commentedon Aug 14, 2026
Mutations are idempotent if you can issue them multiple times and the outcome is the same. A patch (update) mutation is typically idempotent unless you use updatedAt timestamps or issue events on update, a delete mutation is idempotent if it gives the same result whether or not the record existed before the delete (assuming no events). Other mutation types may or may not be idempotent.
martinbonnin commentedon Aug 14, 2026
Did we want to investigate caching those mutations? Is there prior art in HTTP?
benjie commentedon Aug 15, 2026
No, I don't think so. The point of idempotency for mutations is if the connection is interrupted (e.g. if you're doing it from a mobile connection) and you don't receive confirmation, you can safely issue the same mutation again without worrying that you'll change something. For example repeating
mutation {postMessage(channelId:123,message:"hi"){...}}could result in the same message being posted multiple times; whereasmutation postMessage(channelId:123, message:"hi", nonce:123456789){...}}could use the nonce to ensure the mutation only happens once - next time, a different nonce would need to be supplied to perform the next mutation.martinbonnin commentedon Aug 15, 2026
Makes sense 👍