Continuous Evolution of GraphQL Schemas @ GitHub

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.

F34d97ba1bfea0ff5e35a9c198562402?s=128

Marc-Andre Giroux

September 25, 2018
Tweet

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

  15. 15

  16. 16

  17. 17

  18. 18 COMPARE(SCHEMA_A, SCHEMA_B) => SET<CHANGE>

  19. 19

  20. 20 % GraphQL Doctor

  21. 21

  22. 22 Have-to Breaking Changes

  23. 23 Prevention First!

  24. 24 Evolvable Schema Design

  25. 25

  26. 26

  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

  33. 33

  34. 34

  35. 35 Problem: free form text, hard to be consistent.

  36. 36 Ruby API

  37. 37 Ruby API: Resulting IDL

  38. 38

  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

  42. 42

  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
  50. 50

  51. 51

  52. 52

  53. 53 Make it easy for users to evolve their clients.

  54. 54

  55. 55

  56. 56

  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 !