graphql / graphql-over-http Goto Github PK
View Code? Open in Web Editor NEWWorking draft of "GraphQL over HTTP" specification
Home Page: https://graphql.github.io/graphql-over-http
License: MIT License
Working draft of "GraphQL over HTTP" specification
Home Page: https://graphql.github.io/graphql-over-http
License: MIT License
If we release this spec in RFC format (even with "information" status) we can register application/graphql
as official mime type:
https://www.iana.org/assignments/media-types/media-types.xhtml
Combining it with +json
structural suffix we can use application/graphlq+json
as media to for GraphQL request/responses in serialized as JSON.
Prior Art:
application/grpc+json
, see https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#requestsapplication/soap+xml
, see https://en.wikipedia.org/wiki/SOAP#Example_message_.28encapsulated_in_HTTP.29I don't think it should go into 1.0
release but I think it's something we should explore for post-1.0
.
Library developers can miss the efforts of developing a spec of GraphQL over HTTP.
It's important that in order to have interoperability over diferent programing languages or frameworks the developers of this libraries know about this, so they can explain pros and const of every decision made here.
I propose the creation of a file called INTERESTED_DEVELOPERS.md that track:
As an example (of myself):
Hello, just opening a discussion to remind interested devs about our working group meeting on Tuesday, May 26th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-05-26.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @IvanGoncharov
Hello, we'd like to make sure that we're meeting at the best time possible for all folks. If you're interested in participating, please fill out this doodle with the best time for you on the last Tuesday of every month (Tuesday being defined at 00:00 to 23:59 in UTC). I've picked Aug 25 (next day we'll meet) for the poll, but we'll use this time going forward for every last Tuesday of the month.
As a bonus I also included times on Wednesday, Aug 26 if by chance that seems to work better for folks.
https://doodle.com/poll/wmmx4mybrwm6cew8
Deadline: August 21, 2020 I will update our agenda shortly afterwards with the time that works for the most people (hoping there's a clear winner).
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @enisdenjo
Note: there was a poll for last month, but I didn't get that turned around in time to update the meeting. Apologies that you have to do this again.
I think @jaydenseric (?) mentioned issues integrating GraphiQL into the test suite (?). I've spoken with @acao and they would like to help with guidance/etc - could someone please expand on what the issues are/what help is needed? Feel free to move this to the relevant repository. Thanks!
Question marks are because I'm fried, and not confident I have the details right (and our live notes don't help)
Document the agreement that we should require MIME-type, making all existing servers non-compliant. Update the intention of the 1.0 release to reflect the new approach to the spec.
Tools should be able to quickly tell if a server implements the GraphQL HTTP spec or not.
Here's a rough idea of what might work for this:
Client/Tool sends an OPTIONS request to the URL that claims to be a GraphQL HTTP, Response comes with a Header like X-GRAPHQL-HTTP
that includes a link to the published spec?
Hello, we'd like to make sure that we're meeting at the best time possible for all folks. If you're interested in participating, please fill out this doodle with the best time for you on the last Tuesday of every month (Tuesday being defined at 00:00 to 23:59 in UTC). I've picked July 28 (next day we'll meet) for the poll, but we'll use this time going forward for every last Tuesday of the month.
https://doodle.com/poll/2rwvachend53zism
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @enisdenjo
Hello, just opening a discussion to remind interested devs about our working group meeting on Feb 25th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-02-25.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @IvanGoncharov
@IvanGoncharov
@spawnia
@robzhu
@mike-marcacci
@michaelstaib
@jaydenseric
@hemanth
@glennblock
@abernix
@hemanth
@benjie
Zoom can only have one meeting at a time, so please use this link:
Research some other serialization formats and whether they have implications for content-types / status codes. For example, the usual case that we consider is GraphQL over HTTP with JSON as the serialization format. However, there are other serialization formats in use and this may give us insight as to what the constraints need to be support those in addition to JSON in GraphQL over HTTP.
Use https://spec-md.com/ to format the GraphQL over HTTP spec.
(Edited on 7/1 with more info)
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
I believe it would be pertinent and useful to create GraphQL directives for the client-side and server-side:
CLIENT-SIDE EXAMPLE ( @httpCompressed directive):
This directive is used to set up encoding negotiation using the
Accept-Encoding: gzip
HTTP request header while expecting compressed content. When the mode is set to one-off, the response needs to have the HTTP response headerContent-Encoding: gzip
but if the @defer or @stream directives a re used in conjunction with @httpCompressed directive, then the response needs to have the HTTP response headerTransfer-Encoding: gzip, chunked
and the mode will be implicitly incremental even if the mode is explicitly specified as the response will definitely be streamed using either HTTP 1.1 streaming (multipart/mixed response). The above setting tells the GraphQL server that HTTP compression should only be applied when the GraphQL response is above 3000KB.
query GetUserFriendsAndLikes ($id: Int!) {
getUserFriendsAndLikes (id: $id) @httpCompressed(mode: "incremental", above: 3000) {
first_name
last_name
age
gender
friends @defer {
first_name
last_name
age
gender
}
likes
}
}
SERVER-SIDE EXAMPLE (@httpCached directive)
This directive is used to activate HTTP Cache-Control header to either set them or check depending on whether the response goes through a CDN or if the resolver function output data gets requested over the network and the GraphQL server has caching capabilities built around the HTTP caching spec.
type User {
name: String!
age: Int!
salary: Float!
}
type Query {
getAllUsers (id: ID!, page: Int!, pageSize: Int!): [User!] @httpCached(action: "check", freshness: 1, validation: 0)
}
Based on the 2020-05-26 working group meeting, here's the planned actions we'd like to work on next. If you're tagged here and you feel you cannot meet that commitment, please comment or DM me. Also, if you'd like to get involved on any of these actions just post.
(grouped by action owner)
@IvanGoncharov - read #79 and comment
@jaydenseric - add operationName tests
@jaydenseric Continue implementing some of the automated tests in: https://github.com/jaydenseric/graphql-http-test
@jaydenseric (when/if ready this month) open an issue on express-graphql for adding the test/audit suite
@sjparsons Share some stats on how common application/graphql
is from Braintree and other sources if possible.
Finding: Braintree's GraphQL API requires
application/json
currently.
@sjparsons Follow up with Brian, Ivan and others from the GraphQL Foundation to get momentum on the technical transfer of the repo.
Emailed on June 30
@sjparsons Research some other serialization formats and whether they have implications for content-types / status codes.
@sjparsons Document the agreement that we should require MIME-type, making all existing servers non-compliant. Update the intention of the 1.0 release to reflect the new approach to the spec.
@sjparsons Begin file to document the pre-spec state and adoption guide. Include draft structure and preamble
@sjparsons How can the server recognize the client sent a GraphQL Request? Clarify that part in the spec.
I have a question regarding how the response protocol is determined for a request that could POTENTIALLY result in multiple payloads.
accept: multipart/mixed
with non-"Incremental Delivery" operationGiven we have an operation that does not use defer/stream at all:
query { foo }
Should the response then use the application/(graphql+)json
response type or the multipart/mixed
response type?
accept: multipart/mixed, application/(graphql+)json
with non-"Incremental Delivery" operationGiven we have an operation that does not use defer/stream at all:
query { foo }
Should the response then still use the application/(graphql+)json
content-type or the multipart/mixed
response type?
According to the current spec draft, the server should always please the order of the accept header listed content-types if possible. Would that still apply if the server is capable of serving both content-types (accept: multipart/mixed
and application/(graphql+)json
)
accept: application/(graphql+)json
with "Incremental Delivery" operationquery {
foo
... on Query @defer {
bar
}
}
Quote from current Spec Draft:
According to the HTTP 1.1 Accept specification, when a client does not include at least one supported content type in the Accept HTTP header, the server MAY choose to respond in one of several ways. The server MUST either:
Disregard the Accept header and respond with the default content type of application/graphql+json, specifying this in the Content-Type header; OR
Respond with a 406 Not Acceptable status code
Should the server in this scenario still send back multipart/mixed
or raise a 406 HTTP error?
Should the fact that the client sent an operation with a defer or stream directive be a hint to the server that the client MUST be able to parse it? A client not supporting it, would probably not have requested it in the first place?
Should the server be responsible for merging the results and sending them as a single result to the client?
Should the server do the execution with the defer and stream executor functionality being disabled?
GET
methodIs incremental delivery via GET
allowed or intended?
I had a read through the proposal and it seems like Content-Length
MUST be provided for each part. I'm curious as to why this is the case - is it simply because it makes client implementation easier? From a service perspective accomplishing this behavior requires buffering the result of serialization in memory before being written to the response stream, which can have a negative impact on performance in high-throughput services. It's much more efficient to serialize directly to the response stream, and let the clients rely on the boundary markers to determine if a part is complete.
This would necessitate a more complex boundary marker, as proposed by #135.
Should we start submitting our transport spec to ietf
? And how? I've never done this before
How can the server recognize the client sent a GraphQL Request? Clarify that part in the spec.
For GraphQL over HTTP it would be great to standardize few of the directives for describing HTTP metadata. These directives would be useful both for documentation and run time enforcement;
1-Directive for HTTP headers (request and Response) at an operation level
2-Directives for describing HTTP status codes at an operation level
3-Directive for uniquely identifying an operation ( This can be used for the purpose of linking the operation with API samples, error catalog etc.)
4-Directives for supported media types (produces and consumes) at can operation level
5- Directive for specifying security requirements at the operation level (e.g securing ana API operation using an OAuth2 scope is pretty common)
Other Directives (not related to HTTP in general but useful);
authPolicy- directive for specifying the security requirement for an API operation.
tags- For grouping API operations together (This helps wrt documentation to group similar API operations together. For example all wallet operations can be grouped under the tag "wallet-management")
slo-directive for specifying the service level objectives of an API operation (e.g. the 95th percentile response time, error rate etc.)
visibility- directive for API visibility (Public, private and partner public are pretty common categories in APIs).
Happy to discuss these and contribute back. We have many of them defined. We have many of these defined art PayPal. Happy to share them here.
Hello, just opening a discussion to remind interested devs about our working group meeting on Tuesday, September 29th. Please see the agenda and open a PR to add yourself. Note we are meeting at the time we've met at before, 1900 UTC. Feel free to add a topic if you'd like to discuss timing again. Unfortunately, I will not able to join this time, so @IvanGoncharov will facilitate.
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-09-29.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @spawnia @sungam3r @enisdenjo @IvanGoncharov
Acceptance Criteria:
This is a major step for us to make toward the 1.0 release.
This issue will track the status of this work until it's complete.
Hello, just opening a discussion to remind interested devs about our working group meeting on Mar 24th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-03-24.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @IvanGoncharov
Also, please note the scheduled time. It's the same time as usual in UTC, but some of you may live in timezones that have adjusted for daylight savings. Please note the updated time, and/or provide feedback if we should adjust this for daylight savings to accommodate folks better.
We would like to have a pre-spec state and an adoption guide to be release with the 1.0 version of the spec. We'll be releasing some breaking changes and we want to make it clear what implementors will need to do to become compliant.
Tasks:
The AppSync team is interested in participating in the HTTP specification. Here is the AppSync HTTP behavior:
AppSync supports HTTP POST and GET for queries and mutations. The URL for the endpoint is: https://.appsync-api..amazonaws.com/graphql. Query variables are sent in the HTTP POST Body, encoded as JSON or as query parameters in HTTP GET.
{
"errors": [
{
"message": "Request body is empty.",
"errorType": "MalformedHttpRequestException"
}
]
}
{
"errors": [
{
"message": "Unable to parse GraphQL query.",
"errorType": "MalformedHttpRequestException"
}
]
}
{
"data": null,
"errors": [
{
"path": null,
"locations": [
{
"line": 1,
"column": 2,
"sourceName": null
}
],
"message": "Validation error of type FieldUndefined: Field 'badfield' in type 'Query' is undefined @ 'badfield'"
}
]
}
{
"data": null,
"errors": [
{
"path": null,
"locations": [
{
"line": 1,
"column": 23,
"sourceName": null
}
],
"message": "Variable 'name' has coerced Null value for NonNull type 'String!'"
}
]
}
{
"errors": [
{
"errorType": "BadRequestException",
"message": "Missing operation name."
}
]
}
{
"data": null,
"errors": [
{
"path": null,
"locations": [
{
"line": 3,
"column": 11,
"sourceName": null
}
],
"message": "Validation error of type VariableTypeMismatch: Variable type 'Boolean!' doesn't match expected type 'String!' @ 'createEvent'"
}
]
}
~ ยป curl --verbose --location --request POST 'https://3wawwq467zfs7fztm7zbejd2zi.appsync-api.us-west-2.amazonaws.com/graphql' \
--header 'x-api-key: da2-4fg5zsayc5eyzoh7yebkq74h24 ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {\n helloworld\n}","variables":{}}'
> POST /graphql HTTP/2
> Host: 3wawwq467zfs7fztm7zbejd2zi.appsync-api.us-west-2.amazonaws.com
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: da2-4fg5zsayc5eyzoh7yebkq74h24
> Content-Type: application/json
> Content-Length: 53
>
< HTTP/2 502
< content-type: application/json;charset=UTF-8
< content-length: 117
< date: Mon, 13 Apr 2020 23:46:18 GMT
< x-amzn-requestid: 6b317af8-b592-4335-b607-d37cbf87e352
< x-amzn-errortype: GraphQLSchemaException
< x-cache: Error from cloudfront
< via: 1.1 9c60d6224ac0b44e908b5c9dcf70e9a5.cloudfront.net (CloudFront)
< x-amz-cf-pop: HIO50-C1
< x-amz-cf-id: ZYdVK8HL3O0a3miOztDcua7B9OZoxsO-updJhQJpFyG0gpszZSshwQ==
<
{
"errors" : [ {
"errorType" : "GraphQLSchemaException",
"message" : "No schema definition exists."
} ]
* Connection #0 to host 3wawwq467zfs7fztm7zbejd2zi.appsync-api.us-west-2.amazonaws.com left intact
}%
Headers:
:authority: 4oibmd5u5nahvhtdjy5zmm35oa.appsync-api.us-west-2.amazonaws.com
:method: POST
:path: /graphql
:scheme: https
accept: */*
accept-encoding: gzip, deflate, br
accept-language: en-US,en;q=0.9
content-length: 262
content-type: application/json
origin: https://us-west-2.console.aws.amazon.com
referer: https://us-west-2.console.aws.amazon.com/appsync/home?region=us-west-2
sec-fetch-dest: empty
sec-fetch-mode: cors
sec-fetch-site: cross-site
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36
x-amz-user-agent: AWS-Console-AppSync/
x-api-key: <redacted>
Payload:
{"query":"mutation CreateEvent ($name: String!) {
createEvent(
name: $name
when: "Today"
where: "My House"
description: "Very first event"
) {
id
name
}
}
","variables":{"name":"test"},"operationName":"CreateEvent"}
Response Headers:
access-control-allow-origin: *
access-control-expose-headers: x-amzn-RequestId,x-amzn-ErrorType,x-amz-user-agent,x-amzn-ErrorMessage,Date,x-amz-schema-version
content-length: 84
content-type: application/json;charset=UTF-8
date: Mon, 13 Apr 2020 22:57:13 GMT
status: 200
via: 1.1 b4085435efbe95a420f374958bd145bf.cloudfront.net (CloudFront)
x-amz-cf-id: e4g9Byfo3dZD9w5PxM-NCU0IkG45x0ZWL7RiHuNok-NhFFX_oMRvwQ==
x-amz-cf-pop: SEA19-C1
x-amzn-requestid: 422c227f-a63a-4b18-bf28-c375255254de
x-cache: Miss from cloudfront
Response Body:
{"data":{"createEvent":{"id":"61b34b56-e699-4f82-af2e-10a5794a1bda","name":"test"}}}
Headers:
:authority: 4oibmd5u5nahvhtdjy5zmm35oa.appsync-api.us-west-2.amazonaws.com
:method: POST
:path: /graphql
:scheme: https
accept: */*
accept-encoding: gzip, deflate, br
accept-language: en-US,en;q=0.9
content-length: 153
content-type: application/json
origin: https://us-west-2.console.aws.amazon.com
referer: https://us-west-2.console.aws.amazon.com/appsync/home?region=us-west-2
sec-fetch-dest: empty
sec-fetch-mode: cors
sec-fetch-site: cross-site
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36
x-amz-user-agent: AWS-Console-AppSync/
x-api-key: <redacted>
Payload:
{"query":"query ListEvents {
listEvents {
items {
id
name
}
}
}","variables":{"name":"test"},"operationName":"ListEvents"}
Response Headers:
access-control-allow-origin: *
access-control-expose-headers: x-amzn-RequestId,x-amzn-ErrorType,x-amz-user-agent,x-amzn-ErrorMessage,Date,x-amz-schema-version
content-length: 95
content-type: application/json;charset=UTF-8
date: Mon, 13 Apr 2020 22:53:28 GMT
status: 200
via: 1.1 b4085435efbe95a420f374958bd145bf.cloudfront.net (CloudFront)
x-amz-cf-id: mvkpGFwdSOXN200C1_CAvqP69cXrS6lnNyp6RACsj4pMX80hQV1G-w==
x-amz-cf-pop: SEA19-C1
x-amzn-requestid: 495458c1-c9af-484b-b60d-1a460c0a9605
x-cache: Miss from cloudfront
Response Body:
{"data":{"listEvents":{"items":[{"id":"61b34b56-e699-4f82-af2e-10a5794a1bda","name":"test"}]}}}
Hello, just opening a discussion to remind interested devs about our working group meeting on Tuesday, June 30th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-06-30.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @enisdenjo @IvanGoncharov
Is it worth mentioning batch requests? In this case, an array of objects is transmitted via http.
Subscriptions are usually handled over the websockets but they could also utilize http protocol in situations like:
Would the working group consider extending graphql-over-http to include subscriptions over WebSockets ?
Hello, just opening a discussion to remind interested devs about our working group meeting on Tuesday, April 28th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-04-28.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @IvanGoncharov
GraphQL Mutations via GET is very problematic: it goes against the fundamental idea of HTTP GET. It also has security implications: graphql-java/graphql-java-spring#28 (comment)
I would recommend to drop HTTP via GET completely or move it to an optional recommendation with a clear explanation about the potential consequences.
I think we need to answer the question: Does GraphQL over HTTP
describe:
For number 3:
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @spawnia @sungam3r @enisdenjo @IvanGoncharov
Discussion with @IvanGoncharov @ghmcadams @mmatsa
Issue/Background: We want to move along discussion
master
branch always clean, and it's ok to back out changesSummary:
Proposal:
master
would need strong consensusWe'd like feedback from the group.
Any concerns with the Summary? Or the details?
Based on discussion here, we can open a PR.
As discussed in the last working group meeting, there is strong interest in providing a conformance test suite to go along with the spec.
In order to not limit what kind of tests we can run, i narrowed down the choice to testing frameworks that allow running actual code. Some classes of tests are really hard/impossible to implement using only static request/response pairs.
JavaScript TypeScript seems like the obvious choice for the language. It is basically the lingua franca of the web and the most popular GraphQL implementations, including the reference implementation, are written in it.
To organize the tests, we might just use a test runner such as Jest or Mocha, if we want to stick with pure JavaScript. I think that would get us up and running very quickly.
Another route we could go would be to define the tests more abstractly, using a BDD tool such as https://gauge.org/ or http://cucumber.io/. That would allow us to define the test scenarios in more readable plain text and hook up the executable tests under the hood.
For making the actual assertions, https://github.com/visionmedia/supertest seems like a popular and practical choice. Haven't really found much more in that regard, open to suggestions.
Based on the meeting today, here's the planned actions we'd like to work on next. If you're tagged here and you feel you cannot meet that commitment, please comment or DM me. Also, if you'd like to get involved on any of these actions just post.
Planned before next meeting
Later
???? - Draft a standard sample schema - Dependent on list of things to test
Create sample servers to help test compliancy (i.e. graphql-express, graphql-api-koa, etc)
See agenda for notes and more details.
Based on the meeting today, here's the planned actions we'd like to work on next. If you're tagged here and you feel you cannot meet that commitment, please comment or DM me. Also, if you'd like to get involved on any of these actions just post.
Planned before next meeting:
See agenda for notes and more details.
(when we're ready)
@jaydenseric Adding this an issue as it's a better primitive for tracking
I'm with the Foundation and am setting up EasyCLA to manage GraphQL Specification membership signatures. Basically, as a GraphQL Project, we need to make sure all contributors have signed the (free) GraphQL Specification Membership document. The easiest way to do this is to use the EasyCLA bot, which checks each PR and verifies that the contributor has a signed spec membership on file. If they don't, it blocks the PR and provides instructions on how to get covered. Once the doc has been signed once it doesn't need to be signed again. I wrote up some detailed information here.
I've got this enabled for the main Working Group and a number of other repos. I'd like to turn this on fairly soon, and wanted to give you a heads up that it's coming. If you have questions, please let me know.
As discussed/agreed here: #124 (comment)
CC @robrichard
The terms "persisted queries" and "stored operations" are typically used interchangably. The traditional name is "persisted queries", but the term "stored operations" acknowledges that this approach can be used with mutation and subscription operations in addition to queries.
There's lots of different implementations of this feature, often with different aims. Sometimes it's used to block all but a small allow-list of operations. Sometimes it's used to reduce network bandwidth for GraphQL requests. Sometimes it's used to improve HTTP cacheability (GET requests with short URLs).
Relevant links:
Some implementations require queries to be persisted to the server in advance of receiving queries (e.g. at build time); others negotiate the storage of the query with the server for bandwidth optimisation (e.g. automatic persisted queries).
Typically persisted queries replace the query
in {query, variables, operationName}
with another field (typically id
) that indicates an identifier for the operation - perhaps a number or hash.
Typically stored operations remove the query
in {query, variables, operationName}
and instead indicate the operation via a hash or similar identifier in the extensions
property.
One of the optimisations that stored operations enable is that the parse
and validate
steps of GraphQL execution can be performed once per stored operation and cached; future requests for the same stored operation can jump straight to the execute
step.
Server-sent events are a perfect mechanism for informing a GraphQL client that the schema has been updated. They don't require the complexity of websockets, and they are uni-directional.
I'm proposing that when introspecting a GraphQL API, if the header X-GraphQL-Event-Stream
is detected then interested clients should subscribe to the text/event-stream
at that (relative or absolute) URL and when it receives the change
event it should automatically re-introspect the GraphQL schema.
Not much code should be required to implement this, just something like:
// refreshSchema is a function you provide which triggers re-introspection
const streamUrl = response.headers["x-graphql-event-stream"];
if (streamUrl) {
const endpointUrl = new URL(endpoint);
const streamUrl = new URL(streamUrl, endpointUrl);
if (endpointUrl.host !== streamUrl.host) {
throw new Error(
`Stream and endpoint hosts don't match - '${streamUrl.host}' !== '${endpointUrl.host}'`
);
}
const eventSource = new EventSource(streamUrl);
eventSource.addEventListener("change", refreshSchema, false);
eventSource.addEventListener("open", () => { /* ... */ }, false);
eventSource.addEventListener("error", () => { /* ... */ }, false);
}
(You may want to throttle the refreshSchema method.)
This has been baked into PostGraphile for a while; I opened an implementation PR to @skevy's GraphiQL.app a good while ago; and @imolorhe has implemented it independently in Altair. Samuel wrote more about it here: https://sirmuel.design/a-better-graphql-developer-experience-with-x-graphql-event-stream-1256aef96f24. We'll probably be implementing it in the new version of GraphiQL too, once we have the plugin system in place.
What are your thoughts?
It's come up a number of times in our discussions as a working group: We would like to have optional features that can be adopted and if adopted by a server/client then that section of the spec can be applied. I believe we need a mechanism for this.
I know we wish to leave many of the optional features to be defined after the 1.0 release, but I'm wondering whether the mechanism should/could be put in place for the 1.0 release, so that we have a firm foundation and clear runway after the 1.0 to start building extensions and optional features.
I'm interested in hearing (1) opinions on 1.0 or post 1.0 release and (2) ideas about possible solutions for the 2. Communication mechanism described above.
Based on the meeting today, here's the planned actions we'd like to work on next. If you're tagged here and you feel you cannot meet that commitment, please comment or DM me. Also, if you'd like to get involved on any of these actions just post.
Planned before next meeting:
graphql-http-test
See agenda for notes and more details.
Hello folks, I'm cancelling the July working group meeting today since I hadn't had a chance to work through the responses and communicate a new time. We will meet again on last Tuesday of August; later today I'll work through and communicate the responses about times. Apologies for the late notice.
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @enisdenjo
Hat-tip @benjie for keeping me honest.
Hello, just opening a discussion to remind interested devs about our working group meeting Dec 17th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2019-12-17.md
@benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @IvanGoncharov
Hello, just opening a discussion to remind interested devs about our working group meeting on Tuesday, August 25th. Please see the agenda and open a PR to add yourself. Note we are meeting at the time we've met at before, 1900 UTC. Feel free to add a topic if you'd like to discuss timing again.
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-08-25.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @sjparsons @spawnia @sungam3r @enisdenjo @IvanGoncharov
When GraphQL queries contain more than one operation, then an operationName should be present in the payload body. Need to add an audit for this case.
https://github.com/jaydenseric/graphql-http-test
@jaydenseric I'm adding this an issue here, if you want to also reference an issue on your repo that'd be cool.
Hello, just opening a discussion to remind interested devs about our working group meeting on Jan 28th. Please see the agenda and open a PR to add yourself:
https://github.com/APIs-guru/graphql-over-http/blob/master/working-group/agendas/2020-01-28.md
@abernix @balshor @benjie @deinok @ErikWittern @jaydenseric @michaelstaib @mike-marcacci @mmatsa @spawnia @sungam3r
When it comes to sending large scalars over HTTP, @jaydenseric's graphql multipart spec is the de facto standard at this point, being supported by many languages and tools, including Apollo's ecosystem.
There is probably value to either integrating or referencing his spec here.
In your GET example, the space in ($id: ID!) invalidates the request.
http://example.com/graphql?query=query($id: ID!){user(id:$id){name}}&variables={"id":"QVBJcy5ndXJ1"}
Do you recommend clients implementing a graphql api remove all spaces in queries or url encode the query string. For example:
url = 'http://example.com/graphql?query=' + quote('query($id: ID!){user(id:$id){name}}&variables={"id":"QVBJcy5ndXJ1"}')
Sorry, I'm a bit late in posting this... Based on the 24 April 2020 working meeting, here's the planned actions we'd like to work on next. If you're tagged here and you feel you cannot meet that commitment, please comment or DM me. Also, if you'd like to get involved on any of these actions just post.
Planned before next meeting:
application/graphql
as a common format instead of application/graphql+json
for submitting requests. GitHub? Shopify? Braintree (@sjparsons can look into this) How popular is it?A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.