Continuous Evolution of GraphQL Schemas @ GitHub

Evolving an API, let alone a public one, is no easy task. The standard for GraphQL APIs has been to use continuous evolution instead of versioning schemas. While continuous evolution is nothing new in the world of APIs, GraphQL's built in deprecations, type system and query language brings a set of interesting advantages when opting for that strategy.

Evolving GraphQL schemas still brings a lot of questions: Which integrators are using this field? Can we safely remove this deprecated enum value? With hundreds of developers contributing to a single GraphQL API, the ecosystem team at GitHub had to come up with an answer to these questions, and better tooling to help engineers build evolvable GraphQL APIs.

This is the story of how GitHub gained greater confidence in building and evolving GraphQL schemas.

Transcript

1. How people build software ! " Continuous Evolution of GraphQL Schemas
2. @_ _xuorig_ _ Marc Giroux ! Montreal, Canada " 2 !
3. Continuous Evolution? 3
4. 4 - PHIL STURGEON graphql.org
5. 5 EVOLVE'13 | Keynote | Roy Fielding
6. 6 https://tools.ietf.org/html/draft-wilde-sunset-header-04
7. 7 API evolution is the concept of striving to maintain the “I” in API, the request/response body, query parameters, general functionality, etc., only breaking them when you absolutely, absolutely, have to. - PHIL STURGEON
8. Our Mission 8
9. 9 1. Avoid breaking changes the best we can. 2. Make it easy for engineers to evolve our schemas. 3. Make it easy for users to evolve their clients.
10. 10 Avoiding Breaking Changes
11. 11 Accidental Breaking Changes
12. 12 Checked-in GraphQL IDL
13. 13 Checked-in GraphQL IDL
14. 14 Checked-in GraphQL IDL
18. 18 COMPARE(SCHEMA_A, SCHEMA_B) => SET<CHANGE>
20. 20 % GraphQL Doctor
22. 22 Have-to Breaking Changes
23. 23 Prevention First!
24. 24 Evolvable Schema Design
27. 27 Common Design Issues
28. Scalar => Object Type 28
29. Null => Non-Null 29
30. http://bit.ly/evolvable-schema-design 30
31. 31 Make it easy for engineers to evolve our schemas
32. What GraphQL gives us 32
35. 35 Problem: free form text, hard to be consistent.
36. 36 Ruby API
37. 37 Ruby API: Resulting IDL
39. 39 Another Problem: Only fields and enum values... Invalid according to spec
40. 40 Fake It Till You Make It ™
41. Making the change 41
43. 43 Who is using this field?
44. Has this field been used in past x days? 44
45. query { viewer { pullRequests { title description } } 45 GitHub API
46. <query> 46 GitHub API
47. 47 Query Analytics
48. 48 Query Analytics query { viewer { pullRequests { title description } }
49. 49 Query Analytics Type: Query Field: viewer App: xxx Type: User Field: pullRequests App: xxx
53. 53 Make it easy for users to evolve their clients.
57. 57 Schema usage data: personalised deprecation warnings!
58. Learnings & Next Steps 58
59. Deprecating things is hard. 59
60. Built-In Deprecations: A double-edged sword ⚔ 60
61. How can we make API evolution even better? 61
62. Automatic Sunsets? 62
63. Smart(er) Clients? 63
64. Auto Upgrades? 64
65. @_ _xuorig_ _ Thank you! Marc Giroux ! 65 !