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
   

   View Slide

2. @_ _xuorig_ _
   Marc Giroux !
   Montreal, Canada "
   2
   !
   

   View Slide

3. Continuous Evolution?
   3
   

   View Slide

4. 4
   - PHIL STURGEON
   graphql.org
   

   View Slide

5. 5
   EVOLVE'13 | Keynote | Roy Fielding
   

   View Slide

6. 6
   https://tools.ietf.org/html/draft-wilde-sunset-header-04
   

   View Slide

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
   

   View Slide

8. Our Mission
   8
   

   View Slide

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.
   

   View Slide

10. 10
    Avoiding Breaking Changes
    

    View Slide

11. 11
    Accidental Breaking Changes
    

    View Slide

12. 12
    Checked-in GraphQL IDL
    

    View Slide

13. 13
    Checked-in GraphQL IDL
    

    View Slide

14. 14
    Checked-in GraphQL IDL
    

    View Slide

15. View Slide

16. View Slide

17. View Slide

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

    View Slide

19. View Slide

20. 20
    %
    GraphQL Doctor
    

    View Slide

21. View Slide

22. 22
    Have-to Breaking Changes
    

    View Slide

23. 23
    Prevention First!
    

    View Slide

24. 24
    Evolvable Schema Design
    

    View Slide

25. View Slide

26. View Slide

27. 27
    Common Design Issues
    

    View Slide

28. Scalar => Object Type
    28
    

    View Slide

29. Null => Non-Null
    29
    

    View Slide

30. http://bit.ly/evolvable-schema-design
    30
    

    View Slide

31. 31
    Make it easy for engineers to evolve our schemas
    

    View Slide

32. What GraphQL gives us
    32
    

    View Slide

33. View Slide

34. View Slide

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

    View Slide

36. 36
    Ruby API
    

    View Slide

37. 37
    Ruby API: Resulting IDL
    

    View Slide

38. View Slide

39. 39
    Another Problem: Only fields and enum values...
    Invalid according to spec
    

    View Slide

40. 40
    Fake It Till You Make It ™
    

    View Slide

41. Making the change
    41
    

    View Slide

42. View Slide

43. 43
    Who is using this field?
    

    View Slide

44. Has this field been used in past x days?
    44
    

    View Slide

45. query {
    viewer {
    pullRequests {
    title
    description
    }
    }
    45
    GitHub
    API
    

    View Slide

46. 
    46
    GitHub
    API
    

    View Slide

47. 47
    Query
    Analytics
    

    View Slide

48. 48
    Query
    Analytics
    query {
    viewer {
    pullRequests {
    title
    description
    }
    }
    

    View Slide

49. 49
    Query
    Analytics
    Type: Query
    Field: viewer
    App: xxx
    Type: User
    Field: pullRequests
    App: xxx
    

    View Slide

50. View Slide

51. View Slide

52. View Slide

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

    View Slide

54. View Slide

55. View Slide

56. View Slide

57. 57
    Schema usage data: personalised deprecation warnings!
    

    View Slide

58. Learnings & Next Steps
    58
    

    View Slide

59. Deprecating things is hard.
    59
    

    View Slide

60. Built-In Deprecations: A double-edged sword ⚔
    60
    

    View Slide

61. How can we make API
    evolution even better?
    61
    

    View Slide

62. Automatic Sunsets?
    62
    

    View Slide

63. Smart(er) Clients?
    63
    

    View Slide

64. Auto Upgrades?
    64
    

    View Slide

65. @_ _xuorig_ _
    Thank you!
    Marc Giroux !
    65
    !
    

    View Slide