GraphQL quickly becomes a popular way to access the data of your applications through your APIs. It’s a tech agnostic query language that works with many programming languages and databases. Cloud providers also jump on this new trend since it quickly gains momentum. As with all trends, you need to identify if you should spend time on it to learn it and/or implement it. Basically you should answer the question: “is it worth the investment”? This article helps to give an overview of the most common topics around GraphQL so you can make that decision. We will not only highlight the technical aspects but also the business-related ones. GraphQL – what’s good to know?
Quick Introduction
In short, GraphQL lets you create specific queries to request data from your APIs as well as gives you the option to store data. Limit the number of requests by combining multiple individual requests into a single request. A request that is also smarter. You only send the information the API needs to carry out its operation. In response, only the relevant data is returned. It saves time on multiple ends, but you need to master a number of new techniques.
To invest or not?
One of the first questions to answer is: should I invest in it or not. This question can be answered only if you understand the impact that is relevant to your applications and the way they are created. Companies that already have an “API-first” strategy might have an answer to this question. Other companies need to apply the API-first principle as a start since GraphQL is built “on top of” your existing APIs. However, GraphQL can be seen as a substitution for REST APIs. Therefore, you might need to change all of these applications before you can benefit from GraphQL. For sure, refactoring those applications is a lot of work. But there is more. You also need to take into account at least the following topics: design patterns and best practices, versioning, mutations, performance-related aspects, frameworks, and security.
Security
Since security should be shifted left in every DevOps-oriented organization, it’s good to understand which security-related aspects are relevant in GraphQL. Just like regular REST APIs you need to properly implement the ways you would handle authentication and authorization. A lot of experts recommend using JSON Web Tokens (JWTs). The website of ApolloGraphQL offers a lot of information on this topic.
Reduce attack surface
It’s a good practice to reduce the attack surface of your APIs, so this is also a must-have for your GraphQL-based APIs. Don’t reveal too many details about your API schema (this is called introspection), hide informative errors and other sensitive information.
Query protection
Protect your queries using a series of protection mechanisms such as strong input validation, timeouts on multiple components (the queries themselves, on the API gateway, on subgraphs), and use a whitelist of allowed queries. There is even a list of OWASP top 10 tips and tricks to help you here.
External actors
Besides the internal factors, there are also external factors that can pose a threat to your APIs. Consider privacy-related information which your GraphQL APIs write in your log files which end up in monitoring and observability platforms that generate alerts and send out notifications to collaboration tools like Slack or MS Teams.
Off course, there’s a lot more to explore such as validating your GraphQL queries up-front before they are committed to Git and techniques to prevent your GraphQL services from being overloaded.
Investment?
The investment to secure GraphQL-related APIs is quite big if you’re new to the above-mentioned API security topics. However, you need less time and resources in case you’ve got API security high on the agenda.
Design and write good APIs
A GraphQL query is written in JSON. You can use simple tools such as Curl to send JSON to your GraphQL endpoint, just like REST. This is simple and very straightforward. Besides Curl, you can use nearly every other programming language to do this. Keep in mind that you need the following pieces of code: the HTTP method (POST is most common), the JSON content type, the URL To send your JSON document to, and the actual JSON document itself.
There is no need to use a special editor to construct GraphQL. However, if you’re a beginner, the following IDEs can help to make your life a bit easier: Apollo Explorer (a cloud-based IDE free of cost), Insomnia or Postman, GraphiQL as well as GraphQL Editor. Take a look at the website of Retool to explore the different features of these tools.
Key features
These are the key features you need in your IDE to speed up the development of your queries:
- Real-time syntax and error highlighting including a proper description of the issue.
- Code completion for various pieces of source code (variables, object names, data types, etc)
- Proper documentation, also ways to automatically create it
- The option to have an interactive view to enable a real-time preview of your queries
- Example datasets to give you a kick-start
- Grouping of queries based on folders or collections to manage them in a proper manner
- Drag and drop support of components like buttons, tables, fields, etc
Investment?
Learning techniques such as GraphQL should be familiar to every self-respecting DevOps engineer, so the investment on this is considered very low.
Naming conventions
Without proper naming conventions, everything becomes a mess since everyone decides for themselves how to name (data) objects, queries, fields names, etc. GraphQL uses various name styles such as camelCase, PascalCase, and UPPERCASE. It’s good to remember that a lot of GraphQL clients are written in languages such as Java, Javascript, or Swift.
Use naming conventions for the names of your Queries, for input objects, list/array queries, mutations, and integrations. The website of Devland provides a good overview of the most common naming conventions.
Investment?
If you’re already using naming conventions for the other programming languages you use, the investment is relatively low. On the other hand, if you need to start from scratch, this would cost you more time.
Cloud support
At the time of writing many cloud providers also offer support for GraphQL. Just like REST-based endpoints, GraphQL demands its place in the API management spectrum. Let’s explore AWS and Azure in this case.
Azure
Developers on the Azure platform can use API management to expose their GraphQL APIs similar to exposing other endpoints. Some of the key features of what is currently being supported:
- Based on the schema, design a GraphQL API using the existing information from REST or SOAP-based APIs.
- Add your GraphQL endpoint or schema using the Azure CLI, Azure tools, or Azure portal.
- Explore the GraphQL schema and review it before actually publishing it.
- Test your GraphQL APIs by using the Query editor with a built-in testing feature. In essence, this creates a server under the hood.
More information on the API management documentation page.
AWS
AWS offers Lambda to write serverless functions in a number of programming languages. Since GraphQL is built on top of many programming languages, it works very well with AWS Lambda. Instead of manually writing all of the functions to create, read, update and delete data that is served from your backend, GraphQL will facilitate this for you in an easy manner. Besides supporting a single endpoint, GraphQL can also serve data from multiple data sources like other (REST) API endpoints, social media, databases, etc. It’s a lot more versatile compared to REST.
Keep the following terminologies in mind:
- Types: to specify the schema of the resources (field types, field names, descriptions, etc).
- Queries: the actions/queries that the end-user can invoke to the GraphQL-based application.
- Resolvers: fetching data from one or more data sources.
- Mutations: to update, insert or delete data. They work just like the other queries
It’s good to understand that you can focus more on the data structure compared to the boilerplate code to fetch and store data to the existing endpoints.
Investment?
It might take some time to learn how to operate your GraphQL queries into the cloud provider of your choice. Since you need to rewrite your AWS Lamda code, this can take a while. On the other hand, if you can just hook your existing GraphQL queries into your cloud-native solution such as Azure API Management, this helps to accelerate.
Other tips and tricks
Besides the topics which are already mentioned, the following aspects are also important on how to best use GraphQL and not run into multiple problems:
- Your data model is super important. A crystal clear data model helps you to beat performance issues, offers clarity on how to use it, and supports the core concepts of GraphQL (request and return only what you need).
- Don’t support multiple versions of your GraphQL queries. This is different compared to REST since the end-users (consumers of your API) define which fields they need and also expect your application to deliver.
- Learn how to use mutations, since that is a challenging area and can’t be easily compared with REST.
- Avoid code duplication as much as possible, and focus on generated query APIs.
- Implement caching techniques, for example through the usage of the DataLoader framework.
- Learn Javascript if you do not already master it since GraphQL is cross-platform and Javascript offers the most tools, libraries, and frameworks.
Bear in mind that this article can never be complete. Check out the GraphQL tutorial on Tutorialspoint to get started.
Wrap up
GraphQL is a new technique to access your APIs which uses specific queries. Using those queries, you focus on the structure of your only request and return data that you really need. Javascript is the most supported language for GraphQL and you can use a variety of IDEs to build your (data & query) schema. The schema is at the base of your queries, therefore it’s important to design it in the best possible way. This also helps to avoid problems later on such as performance issues or security-related issues that can happen to expose your data to unwanted parties. The major cloud providers offer ways to hook in your GraphQL APIs or provide ways to develop them with their serverless solutions. Sometimes the investment can be a bit big if you do not already practice an API-first mentality. In most cases, you’re good to go.
If you have questions related to this topic, feel free to book a meeting with one of our solutions experts, mail to sales@amazic.com.
