GraphQL Best Practices Resources and Design Patterns
GraphQL become the hottest trend in API design. We already discussed GraphQL in various sections such as the comparison of API architectural styles, as many considerations for GraphQL and RESTful API are similar, since it all boils down to for machines to communication with each other. However, given how popular GraphQL is, it now deserves its own section for our curated collection of best resources.
What is GraphQL?
- GraphQL home page, this is the homepage of graphql, so generally you should start here.
- Concepts of GraphQL
Should you use GraphQL?
Understand the advantages of GraphQL is super important, but at same time it is worth a while to see if your project needs is suitable for it. So there are many articles written on this topic. Here are some below:
- REST and Graphql debate on Stackoverflow
- REST vs GraphQL the good, the bad, and the ugly: an article written by our CEO, one of the most popular read articles on this topic.
- Comparison of different Architectural styles, another section of APIGuide.io that have more in-depth articles on comparing different styles of APIs.
GraphQL design patterns and best practices
Graphql homepage do cover some highlevel best practices, but it doesn’t go into a lot of depth into each topic. There are others articles that goes deeper into each of these topics.
Transport layer: protocol and JSON
- Payload: Theoretically, the data payload can be anything, but again, like RESTful APIs, the payload tends to be in JSON. It’s recommended to setup gzip.
- Protocol: Like REST APIs, GraphQL is most commonly served over http.
Modeling best Practices
For any application, data model will drive many of the design decisions down the road, and can have huge impact on performance and usability of your app.
- GraphQL data modeling
- Thinking in graphs
- How to think in graphs coming from REST
- A tutorial about thinking in GraphQL from Relay documentation
API Versioning
How to do GraphQL versioning correctly? RESTful API versioning has multiple strategies with their pros and cons. GraphQL best practices discourages versioning, because in GraphQL the clients determines what fields or values needs to be returned. Therefore, well designed GraphQL APIs should just continue to return the fields that the clients needs.
- Best practices for API versioning for GraphQL and REST
- API Versions for GraphQL vs REST compared
- This article cautions some of the downside of continuous evolution of your GraphQL apis
As the query patterns for GraphQL can vary so much more, using analytics to understand your API usage can be even more important. If you are curious, we here at Moesif decided to support GraphQL from the ground up when we started our API analytics platform.
Mutations
Mutations in GraphQL is surprising tricky. Below are some of the articles on best practices.
- Design GraphQL mutations
- GraphQL mutation design - batch updates, this is continuation of the above article on the mutation topic.
Should you use Null?
When client requests a data or an object that doesn’t exist, how should you handle it? Unlike RESTful API, where there is 404, you’ll have to hand the concept of null. Here are some good articles on best practices:
Pagination in GraphQL
Like pagination in REST APIs, there are multiple approaches for pagination in GraphQL, such as cursor based or offset based. There are pros and cons to both.
- Apollo supports both cursor based and offset based
- A more detailed tutorial with relay and react for pagination
- A StackOverflow article on pagination in vanilla GraphQL
Caching and Batching
For GraphQL, one of the downside is that you can’t use the HTTP semantics and many standard cache features for browsers and web servers that is battle tested. The team at GraphQL already support a framework called DataLoader for cache.
- Best options for caching in GraphQL
- Caching results in CDN
- Caching on the client side
- An exampling using DataLoader
- A Gist with demo of DataLoader
Authentication and Authorization
What if you want to set permissions by resources? This article talks about some the best strategy for that.
Other topics
- Common problems in GraphQL apps cover issues such as Schema Duplication, Client Server data mismatch, Superfluous Database calls, and general performance issues.
- How to overcome code duplication
Architectural Aspects
Below are the framework to think about how to architecting your backend:
- Interface Layer: This is how client interfaces with your backend. And in many ways, GraphQL is really this layer. Many applications will let client decide to interface with GraphQL or RESTful. It is important to refactor your application to
- Cross Cutting Concerns Layer: (authorization, authentication, logging, permissions, etc.)
- Business Logic Layer: This is your actual business logic.
- Data Layer (or Persistence Layer)
After understand that framework, then look at some of the below articles on some of specific architectural choices.
- Serverless and GraphQL
- Deploying GraphQL to AWS
- AWS Lambda and GraphQL
- GraphQL in Microservices Architecture
- Layering GraphQL on top of REST
- How to Wrap REST with GraphQL
GraphQl resources by programming language
Since GraphQL is cross platform, there are different frameworks, libraries, and tools for different languages.
It is not a surprise that Javascript have the most available tools and libraries. I have an article dedicated to this topic on the tech stack for the GraphQL in the Node.js ecosystem. That article gives a particular breakdown of all the popular technologies in the GraphQL Node.js ecosystem such as
On APIGudie.io, each language specific resources page have sections dedicated to GraphQL. I’ll link them here for convenience:
- Javascript GraphQL tutorials
- Javascript GraphQL libraries or packages
- Python GraphQL tutorials
- Python GraphQL libraries or packages
- Ruby GraphQL tutorials
- Ruby GraphQL libraries or packages
- PHP GraphQL tutorials
- PHP GraphQL libraries or packages
- Golang GraphQL tutorials
- Golang GraphQL libraries or packages
- CSharp GraphQL tutorials
- CSharp GraphQL libraries or packages
- Java GraphQL tutorials
- Java GraphQL libraries or packages
Summary
We do realize the above list isn’t complete. Please let us know if there is any good resources you like by either comment below or send us a message.
