GraphQL is a powerful and flexible query language, designed to be adaptable to a wide variety of use cases across different domains and design patterns. Consequently, most recommendations surrounding GraphQL tend to be opinionated and tailored to specific use cases.
Factors that influence a GraphQL API design
With this in mind, it's crucial to establish clear guidelines on key considerations that influence the design of a GraphQL API:
The consumer
It's no surprise that how an API is consumed significantly impacts its design. We should ask ourselves basic questions to gauge the expectations of an API consumer. Is it a public API or an internal API? If it's a public API, will it primarily serve consumers who are treated as customers? Examples include the Shopify API or the GitHub GraphQL API, which are consumed by third-party applications with a wide range of use cases. Based on this, we also need to carefully choose best practices, update designs, or support various expectations. Conversely, if the API is only consumed by internal services, there might be tighter integration with business logic and minimal expectations of supporting legacy designs. It's also essential to understand what the API is intended to support. For example, if the API is required for multiple frontend applications—such as web and mobile apps—the design should also prioritize the API's proximity to the user and its performance.
