As GraphQL is the star of this publication, we need to contextualize a little about it.
You can also listen to the audio version of this article:
is a query-based language with a focus on APIs, created by Facebook in 2012, which made it open source in 2015, and the processing of these queries take place at runtime, that is, the returned data depends directly on the made query. Maybe you might be wondering:”But isn’t that evident? REST does that too, just change the select on the server-side.”Yes, of course, but what makes GraphQL unique is that the client does the query and not the server, so, yes there will be equal queries being made, but also unique and on-demand queries for every need.
Why we are migrating
We have – and will continue having, until there is a complete migration of the products that consume it – a REST API, as it is often found and made available by many companies. However, there came a time where it no longer met the requirements of some products. This is the case, for example, with the extension of Conviso Platform for Burp.
In some situations it was necessary to use more than one endpoint to get a certain information or perform an operation and, in some of these situations, there was a need to combine between versions of the API itself, making querying or manipulation of data, or even automation routines more laborious and less performatic. We also needed a more complete documentation, that could be updated according to its own development and availability of resources, after all, what good is it to have a toolbox if you don’t know how to use it?
Another demand we had was the need to manipulate more easily the content data displayed/returned to the client, that is, more dynamic paging, number of items per page defined by the user, etc. Taking all these points mentioned above into consideration, it was concluded that GraphQL was the most viable solution for our demands at the time. Therefore, the process of change/migration to this new technology began, and we will give more details about this process in the following topic.
How we changed
Considering the technologies available to implement GraphQL, we sought which would have the lowest impact and/or effort, as the new API could not impact our existing operations, as well we had the need to deliver resources as soon as possible. Thus, we concluded that the best option would be to keep as close as possible to what we already had in Conviso Platform. That is, use Ruby and the some precious gems to make the process be subtle as possible.
Using the lower impact/effort approach, we aimed to partially or fully reuse resources we already had in Conviso Platform. Such as, for example, business rules, authentication, session management, among others, thus making the development time of new features shorter and, consequently, having a shorter learning curve for this technology, since it is possible to create associations with something that already exists. It is noteworthy that in this process it was not possible to reuse everything. There was and will always have some code refactoring, as the intention is to always improve processes and operations.
To consolidate and test the gems, we performed some proof of concepts scenarios. In other words, queries were implemented in the GraphQL API and benchmarks were performed, and some of the criteria evaluated was speed, usability, etc. One of the benchmarks that presented a surprising result was speed, as we made a query to consult the projects that Conviso’s employees have access to, and the utilized query is available below.
query{
listProjects{
id
occurrences{
id
}
}
}
In this query, we can identify that all projects id’s are consulted and, from these projects, all linked occurrence id’s – reported vulnerabilities and notifications. This query returned more than 7600 projects and their occurrences, but it only took an average of 30 seconds to process all this information.
Benefits
In a short time of use, it was already possible to identify some of the advantages that GraphQL has to offer, and we will tell you a little about some of them below.
Speed
It’s always a delicate terrain when it comes to speed benchmarks, as there are many factors that can come into play. Some examples are, connection latency, server processing, among others. However, as seen above, more than 7600 projects and their respective occurrences were returned in an average of 30-40 seconds.
Development agility
There was a drastic reduction in the development and learning curve of new operations.
Documentation
As GraphQL is strongly typed and the documentation is written in the code itself, during development, there is no way to leave it to be done later. In other words, as resources are developed, they will be documented and will be made available simultaneously. It is noteworthy that GraphQL clients usually provide interactive documentation during its use. But it is also possible to offer it in a more popular way like our public documentation.
Completion and future work
Taking into account all aspects presented and improvements seen with the use of GraphQL, we will continue to migrate resources, as well as ours products and services to consume and use this new API. There will also be a need to expand the resources available through it, in this way, all future API related development will be and use GraphQL.
Relevant content:
