What can GraphQL do for your API?

Whether weaved into an already existing application or included as an integral part of an application's architecture from day one, an API is a powerful tool in a developer's arsenal. When properly implemented, it can be quite an important factor when it comes to designing the user experience, communicating between software components and providing the building blocks themselves.

However, an unsatisfactory API may become more of a curse rather than a blessing:

• it can drive up the costs,
• case security problems,
• raise the project’s complexity & deteriorate the ease of use in general

Let’s take a look at ways in which GraphQL can help avoid some of the pitfalls of making an API.

Schema as a source of truth

If not carefully planned out, an API architecture can start bleeding money by ever-increasing management and infrastructure costs. GraphQL tackles this problem by forcing its developer to prepare a clearly defined schema (GraphQL Editor comes in handy) and, at the same time, limiting the amount of data returned specifically to the requested scope. Designing a schema should incorporate various ideas from a multitude of people working on or with the API in order to create a broad scope of possible use-cases. Due to the fact that schemas naturally evolve by deprecating some fields and adding new ones, this makes GraphQL an elegant answer to swollen, cumbersome APIs. The previously mentioned narrowing of data returns solves the common issue of over-fetching.

Source: undraw.co

GraphQL makes it simpler

Another cause for a headache that a potential developer might encounter is excessive complexity combined with convoluted documentation. It is of the utmost importance to know how something behaves in certain conditions and why it works in a particular way. This is made nearly impossible, or at least not cost-effective if the developer cannot find the answers that are sought in the documentation surrounding an API. GraphQL, having been adopted by many communities around the programming world, has the benefit of a continuously growing and largely active developer base. This greatly enhances the experience a potential engineer might have as it makes finding the right tools for the job quite simple.

Security

Security needs to be taken into consideration. It is quite likely that an API can be explored by certain individuals as a possible gateway to extracting sensitive data or harming the application in other ways. Allowing such malicious attacks to affect the intended user can really tarnish one’s reputation as a reliable programmer. Although GraphQL allows for limiting the scope of possible queries to a prearranged whitelist, there are other, more flexible ways of handling the problem. Setting a cap on how many requests can be made in any given period of time is a common preventative measure for DDoS attacks.

Source: undraw.co

Conclusion

The very nature of GraphQL appears to solve many of the issues plaguing a plethora of other APIs. Furthermore, should any other problems arise, they will have surely been already tackled by the rich and vibrant community which surrounds this query language. These factors combined make GraphQL a very appealing option when considering implementing an API.

---

A guest blog post from GraphQL Editor blog by Carl Matte; Sources: MarvelApp.com, Netlify.com, Devops.com

---

Speed up your GraphQL API development

GraphQL Editor is a supportive tool for both advanced GraphQL users as well as those taking their first steps with GraphQL APIs. Our all-in-one development environment for GraphQL will help you build, manage & deploy your GraphQL API much faster thanks to dozens of built-in micro features.

Comments

[Rolf Streefkerk]

OpenAPI already solves all the issues related to schema that you outline in this article.

Where do you think security improves over the "standard" REST API's?

[rhymes]

I believe there are some misleading statements in this article. The premise seems to be "lots of non GraphQL APIs are bad, use GraphQL so they won't be bad", but this is obviously not true, as REST(ish) APIs can clearly be enough in a lot of cases.

Understanding strenghts and limitations of each technology makes programmers better at their jobs (and improves their skills of discernment) more than "A is bad, B is great".

For example:

it can drive up the costs
cause security problems
raise the project’s complexity & deteriorate the ease of use in general

These are definitely valid issues but there's no reason why they can't be issues in GraphQL APIs as well. Unchecked and/or recursive GraphQL queries will definitely drive up costs if not correctly engineerd. GraphQL is practically a layer on top of HTTP so there's no reason why it can't have security issues and complexity is a debatable issue, since lots of tools around GraphQL are not easy to learn, just check Apollo and Apollo's tools's documentation :D

True, REST itself can be a steep learning curve (and it is to be fully implemented) but I don't think decontextualized blanket statements help the conversation.

Schema as a source of truth

I agree that the builtin schema is a real and objective advantage. You can have schemas with OpenAPI and JSON schema but the fact that they are not "builtin" and enforced means that they can be optional, and optional often means "they are not there".

The previously mentioned narrowing of data returns solves the common issue of over-fetching

You can design your REST API to allow it to query a custom list of fields. Underfetching is clearly a problem that's addressed by GraphQL by allowing you to select multiple resources at once

The genius of GraphQL lies in the fact that we move lots of control from the server to the client. It's not a surprise there are tools that automatically generate GraphQL servers from schemas or from SQL DBs with little to no code, because most of the control is moved back to the client, instead REST APIs tend to leave little control in the client hands. But REST has OpenAPI 3 with tooling to generate clients, mock servers, do schema validation and so on. It's not like there's nothing :D

You can literally call a REST API with any HTTP library you have around with nothing to no layers on top of "send this method to this URL with these params and these headers". Though you could use a simple HTTP with GraphQL as well, you'll quickly find out it's a bit more complicated than that :D

This is made nearly impossible, or at least not cost-effective if the developer cannot find the answers that are sought in the documentation surrounding an API.

If the API is documented or with a schema, it's not "nearly impossible" to find answers :)

GraphQL, having been adopted by many communities around the programming world, has the benefit of a continuously growing and largely active developer base.

It's like you're trying to say "the GraphQL community is growing, therefore it's better" 👀

The very nature of GraphQL appears to solve many of the issues plaguing a plethora of other APIs.

I don't think this is a fair conclusion based on the content of your article ☺️ As, in the best case scenario, you're describing some non REST APIs you've probably encountered in your professional life, it is not an intrinsic limitation of all non GraphQL APIs.

I understand your frustration, but it seems to be directed more at certain APIs than the concept of (real) REST itself.

I think this, from ThoughtWorks Radar, November 2019 is a more balanced analysis of GraphQL:

We've seen many successful GraphQL implementations on our projects. We've seen some interesting patterns of use too, including GraphQL for server-side resource aggregation. That said, we've concerns about misuse of this framework and some of the problems that can occur. Examples include performance gotchas around N+1 queries and lots of boilerplate code needed when adding new models, leading to complexity. There are workarounds to these gotchas such as query caching. Even though it's not a silver bullet, we still think it's worth assessing as part of your architecture.

I love this sentence from these slides on a critical review of REST and GraphQL:

API community is still relatively small. We should work together

Neither REST nor GraphQL are going anywhere, anytime soon. Let's work together ;) (BTW SOAP is still huge outside our hype-fueled web communities :D)

I'm going to list some thoughts about both in random order:

• Most APIs we know and use are not REST, or at least they are fully not, hence the lingo "RESTish" or "so called REST". This is because a full REST API has a steep learning curve. This is well described in Richardson Maturity Model. Most "RESTish" API are Level 2 at most. Level 3 should be a prerequisite to use the word "REST" (discoverability or HATEAOS), it is in theory, but we still use the word REST for the other levels. DEV API is Level 2.

• REST is super cacheable and scalable. You can use many types of caches transparently because it can use all the HTTP capabilities, in addition to server side caching and edge caching. You can use API gateways like Kong to split your monolithic REST API or to delegate authentication to the entry point instead of your application code. There's a lot you can do :)

• GraphQL is much better at schema evolution (both are similar on deprecation if you use OpenAPI 3) and it has lots of tooling around the builtin schema (your editor being one of them :D). But it's not like there's nothing for REST...

• GraphQL kinda throws away part of the internet infrastructure by (almost always) embedding read requests in POSTs

• REST a steeper learning curve than GraphQL (in the sense that requires learners to know HTTP well)

I'll leave you with some resources:

• REST vs. GraphQL: A Critical Review

Whether you say yes to REST, so-called-REST, or GraphQL, it is essential that you understand the consequences of the noes you tell to the other styles. What aspect are you buying when you say yes to a particular style? What other properties are you loosing when you say no to others?

• GraphQL vs REST: Overview

REST and GraphQL are totally different
GraphQL isn't a magic bullet, nor is it "better"
You can definitely use both at the same time
GraphQL is dope if used for the right thing

If your API is not using hypermedia controls, then GraphQL could be a more relevant approach, because you weren't really using REST anyway.

This to stress that the limitations mentioned aren't inherent of non-GraphQL APIs, they, when they appear, are a byproduct of bad architecture, which can happen with every technology :D

• GraphQL vs REST: Caching

Basically this article explains how out of the three layers of caching (client, network and application), REST over HTTP can use all of them and GraphQL can't use network (I'm aware you can use GETs with GraphQL but most clients don't, and you still have the limitation of the URL length, and the opaqueness of the query string). DEV API relies on network and less often application caching. Switching all the network caching logic to the application server would raise costs in the short term and not be transparent to the server developer (CDNs exist for a reason :D)

In an ideal world, all clients would implement client caching, but a lot don't. Many HTTP clients either make it easier, or handle it seamlessly for clients, but they utilize the same parts of the HTTP specification that cache proxies do: Etag, Cache-Control, etc. These approaches work for endpoint-based APIs, but not for GraphQL.

which is the reason why many GraphQL tools have to be re-created from scratch. If you look at tools you'll notice they have to reinvent HTTP caching (freshness, stale content, invalidation, and so on) because GraphQL can't use those. And not all GraphQL libraries do the same thing, while with REST-HTTP you can use any library in any language and as long as it implements HTTP/1.1 caching you know they'll behave the same way (well, minus eventual bugs :D)

I have implemented a GraphQL server in Go once and I noticed how in many languages other than JS the tools were subpar or limited (it's not a coincidence that the majority of documentation and tooling revolves around GraphQL in JS), while full HTTP clients are a given in any language. So yeah, great tooling if you use JS, a little bit less in other languages as the communities noticeably shrink in size. The "REST community" doesn't really change in size as implementing a functioning HTTP client is kinda of a prerequisite both for REST-over-HTTP and GraphQL-over-HTTP

Building a super-flexible API for a lot of different clients making loads of different requests? Either GraphQL or endpoint-based APIs will have the same limitations when it comes to application caching and structuring data, so use other pros and cons to help you decide.

I love the conclusion:

However you look at it, GraphQL certainly isn't "better" at caching, but it might force API developers to structure data in a more scalable way. Maybe that is a massive waste of time as developers spend months prematurely optimizing an API before its even launched, or maybe it will help get the API "web scale" nice and early. You decide.

As I said in the beginning of this massively long comment (sorry!!), technology choices aren't inherently bad or good, the truth is most of the time "it depends" :D