Member-only story
GraphQL API Design Best Practices: a summary of “Lessons from 4 years of GraphQL” by Lee Byron
An executive summary of some timeless best practices for designing your GraphQL API’s, excerpted from GraphQL co-founder Lee Byron’s presentation at GraphQL Summit — Lessons from 4 years of GraphQL.
(The full presentation is excellent and available on YouTube here: https://www.youtube.com/watch?v=zVNrqo9XGOs).
In this presentation, Lee outlined some best practices based on 4 years of experience for key questions to leverage when designing your GraphQL interface or API’s.
Even with additional time passing from that presentation, these best practices are still ‘best practices’ imo and valuable insights. Thus I felt it might be helpful to summarize these and make them available in a more compact text format here on Medium, rather than having them available solely embedded within a longer 1 hour plus video presentation.
Thus, some key Best Practices for GraphQL API design, developed by Lee Byron, summarized for your consideration below:
1 — Naming Matters: You can’t expect to go back and refactor once a field name is published, so putting some thought into naming ‘up front’ matters.
A best practice benchmark to guide your naming is this question: “Would a new Engineer understand this?”
You don’t want just ‘good names’, you also want names that are ‘self-documenting’. (Thus no code names or server side tech terms).
Visual tools like GraphiQL are used far more than reading any documentation. Thus, developers are likely to build their queries based solely on field names and hence, the need for clear and self-documenting names.
2 —Think ahead and Design for the future: Naming also matters because GraphQL is designed to be ‘versionless’. In other words, fields may be added over time but ‘breaking changes’ are incredibly rare and avoided at nearly all costs.
Thus you want to think one step ahead with this benchmark question:
Key question: “What would version 2 of the product look like?”
Take the time to think about how your product is likely to evolve and make sure the current API is ready to…
