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…