Video recording: https://www.youtube.com/watch?v=bCXQsfIgTng
- Introduction of attendees (5m, Lee)
- Agree to Membership Agreement, Participation Guidelines and Code of Conduct (1m, Lee)
- Determine volunteers for note taking (2m, Lee)
- Review agenda (2m, Lee)
- GraphQL Foundation Turns 1! See the Annual Report: foundation.graphql.org/annual-report-2019
- Custom scalar specification URIs (5m, Evan Huus / Matt Farmer)
- Status check, still waiting on graphql-js
- Input union RFC (5m, Evan Huus / Vince Foley)
- We said we'd have a working session with the champions but couldn't schedule something. Do we want to try again or find a different process?
application/graphqlmedia type status (10m, Benjie)- Referenced by graphql.org - "Serving over HTTP"
- Not officially registered? RFC6838 - Media Type Specifications and Registration Procedures and IANA media types
- Other derivatives, e.g.
application/graphql+jsonfor{"query": "...", "variables": {...}, "operationName": "..."}
- Specification Membership Agreement
- Participation Guidelines
- Code of Conduct
- Benjie
- No changes.
- Looks like Lee wrote it, but really it was Brian and Chris who did most of the work
- Check it out!
- Share it amongst your communities
- Lee: Members can join the GraphQL Foundation directly without needing to be a member of the Linux Foundation
- Robert: Amazon would like to include a lot more information in future beyond the Amplify stack - want to make it clear that Amazon uses GraphQL in a lot more places than just Amplify
- Evan: Status check, still waiting on graphql-js (though that's started moving forward again now)
- Ivan: Released 15.0.0, in a week would like to add a new feature release. Will try and finish review today.
- Ivan: Question: if we change the "specified by" URL on a scalar, technically this is a breaking change because it's an identifier on the client side, and the client might use it. Should we treat this as a breaking change?
- Ivan: if URL changes, because it's opaque, we cannot detect if it's breaking or not
- Morris: we don't know what it means when the string changes - it may or may not be a breaking change.
- Lee: we also need to clarify what we mean by "breaking". Really there's different categories of breaking changes: if you take an identical query to a server after a change - will you get something meaningfully different, or will the query no longer be valid? This is a truly breaking change - breaks backwards compatibility. (This would be a high value thing to define as a breaking change.) There's also "dangerous change" which is not "breaking". Client side tooling relies on introspection to do stuff, if we change these things it may cause headaches for client-side tooling. Code-generation at Facebook inspired the initial "dangerous change" rules. Think of these as "forward breaking changes" as clients will pick these up in the future and may have issues.
- Ivan: I agree with Lee - usual clients don't use introspection in production, so once the app is compiled and released most clients wouldn't notice the difference.
- Robert: can we try and document the differences between these different kinds of breaking changes?
- Lee: absolutely, that's definitely a gap in the spec.
- Matt M: even some of the "breaking changes" are not necessarily always breaking changes - e.g. changing a type to an interface may not break client queries (but it also might, because
__typenamemay change) - Lee: definitional rigour on what it means to be a breaking change is an issue. Huge opportunity if someone wants to take a stab at this/framing up the problem. This is one of the biggest missing parts, and people trip up on it a lot. Even we have more questions than answers about this at this WG!
- Lee: this is waiting on getting merged and released so that we can move it to the final stage.
- Lee: Ivan - what do you recommend for code review in the future? Are additional hands required? Was it just a timing issue with getting v15 out?
- Ivan: it was a very busy month for me, mostly 15.0.0. Reviews are really helpful, and answering questions on graphql-js is also really helpful. Some of the items don't require deep knowledge of the codebase. I'm always happy for others to discuss things. We can also add custom ESLint rules; we're now at 100% coverage so I don't need to tell people about lack of coverage. I need to invest more in tooling like GitHub Actions.
- We said we'd have a working session with the champions but couldn't schedule something. Do we want to try again or find a different process?
- It's nor surprising given global events that we've not managed to make this happen in the last month!
- Lee: we should put hard dates on this otherwise it's going to crawl.
- Evan: I'll coordinate with Vince and try and find a date that should work for everybody.
- Lee: should we set up a channel in the Slack to discuss that. There's a working group channel in the GraphQL Slack channel called "#wg" - we can discuss in there.
- Lee: part of the reason I miss things on GitHub is that I get hundreds of emails per day from GitHub, so it makes it hard for me to see what's important vs what isn't.
- Ivan: Vince thinks that @oneOf should be added anyway; and it seems that more and more people are feeling this way. A direction we could take in this is to discuss if we all agree that @oneOf is a good solution even if it doesn't cover the entire problem space.
- Michael: it would be one of the cheapest to implement.
- Lee: small surface area changed. I don't disagree, but my chief concern is presenting multiple ways to do the same thing. I don't want to get ahead of ourselves and follow that path before we know that it is wise.
- Ivan: one thing that people have discussed is to have a variant type for input types and also potentially output types. "Enum types" in Rust? Boxed values. Variant types are useful on their own and can solve other problems we have with mutations - e.g. the response type being error or data. I've not formalised anything particular, but wanted to share this idea. Something to think about before the next dedicated meeting.
- Lee: definitely a compelling direction.
- Referenced by graphql.org - "Serving over HTTP"
- Not officially registered? RFC6838 - Media Type Specifications and Registration Procedures and IANA media types
- Other derivatives, e.g. application/graphql+json for {"query": "...", "variables": {...}, "operationName": "..."}
- And also in server responses (e.g. the json response from servers have a specific form we could specify)
- The graphql-over-http working group is interested in formalizing this somehow (IANA registration?)
- Is anybody aware of places this has been used/formalized already?
- Lee: MIME-types are super gross (millions of them, parsing is hard), and I’d like to only adopt one if it’s the solution to a real problem.
- Benjie: one use case is distinguishing between graphql-layer errors and other general json/html errors on the client if the server responds with a non-200 code.
- Ivan: requires to publish formal RFC to register mimetype, it’s not a short/simple process, maybe 4-6 months
- If we publish mimetype now we can’t change it, so we should figure out graphql-over-http spec first so we have something we’re happy with to formalize
- Evan: in practice application/graphql seems to be universal already
- Benjie: gql-http wg is thinking that any other 2xx status code is invalid (with a graphql payload?), if you think this is wrong please speak to the wg
- Ivan: what about etags/not-changed?
- Lee: we could do any HTTP code not referenced here has undefined behaviour
- Matthew/Benjie: at least three mimetypes?
- application/graphql
- Json format for server response
- Json format for client request?
- Not clear if this one is actually useful
- Robert: there are many profiles, maybe we need an options query or something
- Lee: we can make it extendable to support hand-off for subscriptions, streaming, etc. Some mechanism to expose this would be good. To say at the transport “my server supports this”
- Benjie: definitely something that’s being discussed, but for our first round of the spec we want to just capture how it’s already being used in the wild
- Ivan: could we get statistics on how different people are using?
- Evan: I can get stats from Shopify’s public APIs
- Lee: 200 status code should only be used where {data: {...}, ...} - i.e. the "data" field is non-null. Anything where "data" is null or not present then it MUST return non-200.
- What does that mean for batching?
- Lee: Facebook will return a set of status code / response payloads
- Lee: spec should be what should be the case, but needs to represent reality. Maybe we need a documentation rather than spec to describe the status quo. "This is the Shopify way; this other thing is the Facebook way". The HTTP spec may break the status quo.
- Lee: the earlier you address the breaking changes for the minimal spec the easier it'll be to advance it in future.
- ACTION - Benjie - discuss this with GraphQL HTTP Working group.
ASIDE:
- Benjie: how do we access this recording?
- Lee: great question. It's complex currently.
- Michael: if you go to Zoom website -> recordings after a few days (maybe over a week due to Coronavirus) you can download a version that you can upload to YouTube. You can also stream directly to YouTube.
- Lee: the issue is that we need YouTube to remove the flag that limits the length of the upload for the GraphQL Foundation; we're working on resolving this with YouTube! Worst comes to the worse we'll create a Box account.
Back on topic:
- Evan: Shopify uses 200 for everything. There's a class of errors where it's not clear who is responsible for the error (throttle error vs query execution error). The client shouldn't need to think about this.
- Lee: does it make sense to return non-200 for invalid GraphQL queries (e.g. bad syntax?)
- Michael: we return 200 status code for errors too. A 400 would mean something outside of the GraphQL context.
- Gabriel: we're doing the same thing. There are some situations where we don't return 200 e.g. authentication but we don't return GraphQL errors here. This helps monitoring of the errors because looking into GraphQL errors is costly. Also helps us to detect issues that are not GraphQL errors. E.g. an invalid GraphQL query would not be a GraphQL error
- Michael: Validation errors, a 400 is too strong. We wouldn't look into the GraphQL errors. This isn't only the spec validation, it could also include custom validation rules.
- Gabriel: we draw the line at whether we were able to parse the query at all. Once we can get into resolvers then it's a GraphQL error.
- Lee: I'm 100% onboard with what you originally pitched now.
- Lee: my desire is that if you get a 200 then you have a non-null data field - we reached execution. (There may have been errors, but we at least started.) Everything else indicates that we couldn't start executing - e.g. the query is invalid, so we couldn't start, or something else went wrong. This should be non-200.
- Lee: I completely agree that once you start layering other HTTP services on this you cannot trust non-200 status codes.
- Gabriel: it's all about drawing the line between GraphQL and not.
- Lee: does using the MIME type indicate sufficiently the difference between the error happening in the GraphQL layer or not?
- Lee: the question is really "can I process this response as a GraphQL response" and the rule seems to be 200: yes, non-200: no. This is conflating things.
- Gabriel: we use a header to indicate this.
- Benjie: e.g. "X-Is-GraphQL"
- Michael: "X-*" headers are deprecated now.
- Ivan: we should study prior art. SOAP has MIME type (application/soap+xml or similar) but it's not registered. Same for gRPC. Putting it inside the official database is secondary - it doesn't prevent us from using MIME types. I think MIME types are the right choice.
- Lee: content negotiation is also a good way to figure out what the server does/doesn't support - does it support GET or POST or application/graphql or JSON etc.
- Gabriel: if we use a broader header then it can open the door to further features later.
- Ivan: MIME should only be used for the content type, not to describe how you're sending it. We can use it to figure out what's the payload is, but we shouldn't use it to negotiate the way that the payload is sent.
- Ivan: application/graphql is useful for SDL schemas. We can finally have official suffix for filenames (e.g.
.graphql). - There is a #graphql-over-http channel on the GraphQL Slack for anyone who wants to get involved.
- What's the status? How can we help with TypeScript?
- Ivan: we need to coordinate the release plan: what versions we support, for how long. Most of the security issues in GraphQL.js have been DoS attacks. We should greate graphql-js channel. I can schedule a call to discuss as I have access to GraphQL Foundation Zoom.