Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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.

Marc-Andre Giroux

September 25, 2018
Tweet

More Decks by Marc-Andre Giroux

Other Decks in Technology

Transcript

  1. How people build software
    !
    "
    Continuous Evolution of GraphQL Schemas

    View full-size slide

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

    View full-size slide

  3. Continuous Evolution?
    3

    View full-size slide

  4. 4
    - PHIL STURGEON
    graphql.org

    View full-size slide

  5. 5
    EVOLVE'13 | Keynote | Roy Fielding

    View full-size slide

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

    View full-size 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 full-size slide

  8. Our Mission
    8

    View full-size 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 full-size slide

  10. 10
    Avoiding Breaking Changes

    View full-size slide

  11. 11
    Accidental Breaking Changes

    View full-size slide

  12. 12
    Checked-in GraphQL IDL

    View full-size slide

  13. 13
    Checked-in GraphQL IDL

    View full-size slide

  14. 14
    Checked-in GraphQL IDL

    View full-size slide

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

    View full-size slide

  16. 20
    %
    GraphQL Doctor

    View full-size slide

  17. 22
    Have-to Breaking Changes

    View full-size slide

  18. 23
    Prevention First!

    View full-size slide

  19. 24
    Evolvable Schema Design

    View full-size slide

  20. 27
    Common Design Issues

    View full-size slide

  21. Scalar => Object Type
    28

    View full-size slide

  22. Null => Non-Null
    29

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  25. What GraphQL gives us
    32

    View full-size slide

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

    View full-size slide

  27. 37
    Ruby API: Resulting IDL

    View full-size slide

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

    View full-size slide

  29. 40
    Fake It Till You Make It ™

    View full-size slide

  30. Making the change
    41

    View full-size slide

  31. 43
    Who is using this field?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  34. 47
    Query
    Analytics

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  38. 57
    Schema usage data: personalised deprecation warnings!

    View full-size slide

  39. Learnings & Next Steps
    58

    View full-size slide

  40. Deprecating things is hard.
    59

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  43. Automatic Sunsets?
    62

    View full-size slide

  44. Smart(er) Clients?
    63

    View full-size slide

  45. Auto Upgrades?
    64

    View full-size slide

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

    View full-size slide