ALICIA WILLIAMS: Hi, I'm Alicia.
And today, I'll be talking to you
about how to apply best practices of REST APIs
to GraphQL.
[MUSIC PLAYING]
GraphQL is an open source data query and manipulation
language for APIs and a runtime for fulfilling queries
with existing data.
It's a new way to think about APIs.
With GraphQL, you can send queries
to get exactly the data you're looking for in one request.
GraphQL can enable front and backend teams
to collaborate more smoothly when developing applications.
Let's look at an example of a GraphQL query.
Here, we are querying for user data with the ID of the user.
The first thing to note about the query and the response
is that they are identical.
This is because GraphQL is typed,
meaning that what you ask for is what you get back.
We are simply just saying, get me the user with this ID
and return me back their name, posts, and followers.
Now let's compare this to how we would get the same results
using a REST endpoint.
Here, we have had to define three separate endpoints
in order to have the ability to access the same data.
Some of you might say that you could
reduce this down to just one endpoint
by returning the entire user object in the first request.
This would be seen as overfetching of data.
One key difference to note here is that with GraphQL, you
know which objects and data you have
available with each query, so you can specify
the shape of the data you would like back from the server.
With REST, you can't really define
what is returned to you, as the server decides this.
So we can think of GraphQL as a single endpoint
upon which we have a set of executable queries
that map to a schema of the data.
There are three key benefits of using this approach.
First of all, all data exchange is
performed at a single endpoint.
That means granularity for data load,
execution of requests in parallel, and query planning.
It also means if one resolver fails, the rest of the query
can still resolve and return useful data.
Secondly, the real strength is in the query language.
You can declare which schemas you want the data from
and the format of that data, which prevents overfetching
and underfetching of data.
And thirdly, availability of native integration
with the ReactJS UI framework and other client libraries
considerably increases productivity for developers.
GraphQL is great, but how does it compare to REST?
There are a number of differences between the two,
and I'll highlight four of these.
When we compare the endpoints, REST
makes many smaller requests to many endpoints
and the URL taxonomy is used as a logical API resource manager.
GraphQL, on the other hand, makes requests
to one endpoint, which results in longer and larger queries
for customer data.
REST uses HTTP verbs and generally uses JSON XML
in order to exchange that data.
GraphQL uses POST most of the time
and also leverages different query types
specified inside the protocol, not in HTTP.
Even though GraphQL uses a custom query
language on the request, JSON is returned as a result.
When we compare documentation, we'll
see that REST uses open API specifications,
while GraphQL uses a schema-generated documentation.
Frequently, we see customers using GraphiQL or GraphQL
Playground to interact with schema-based GraphQL endpoints.
From a discovery perspective, the portal
offers a veritable playground for developers
to try out APIs before they use them in their code,
while GraphQL comes with a built-in playground that
enables users to explore new queries on the fly, including
automatic tab completion.
While the two solutions are very different,
there are a number of best practices in REST APIs that
can be applied to GraphQL.
Let's quickly look at these best practices.
Consistency in GraphQL starts with well-formed GraphQL.
And we can apply the best practices of well-formed REST
here.
Here's an example.
You would never expect a well-formed REST query
to be a list of employees by department.
Rather, a well-formed REST query would be a resource.
A graph hierarchy is fundamentally
a data-driven hierarchy.
It is not a functional hierarchy,
like an object model.
We should be treating GraphQL like Java functions.
In other words, be data-oriented, not
function-oriented.
The second best practice is around
submitting and retrieving data.
Those are not always mirrored operations.
In REST, we frequently submit and receive data
from different URLs.
In particular, when retrieving data
from multiple services in a microservice architecture,
Command Query Responsibility Segregation--
CQRS-- is common.
As we think about how this applies to GraphQL,
we need to consider that query mutations can get very complex
very quickly, especially with many different types when
submitting very little data.
Applying CQRS to GraphQL can help us avoid this challenge.
The third is optimizing for reusability.
In REST, we think a lot about our URL taxonomy,
pagination, and filtering, because developers can then
predict what the behavior will be of any API they call.
In GraphQL, we should be doing the same thing.
With GraphQL, it is important to be careful with schema
stitching, because to the developer,
the representation looks like one big graph.
But the behavior of the JSON returned might be different.
So relay cursor connections and input hints
should all present uniform behavior,
regardless of the portion of the graph being requested.
Even with the best practices I mentioned,
there are a number of challenges with GraphQL deployments.
These revolve around authentication
and authorization.
For example, GraphQL doesn't solve authorization
and does not support authorization
for schema browsing.
GraphQL doesn't support a standard
for throttling or quotas.
It does not have a unified view of analytics,
which means expanding the view of APIs from simple metrics
to business and operational impact metrics
can be challenging.
And it is based on a single endpoint, which
means that there are no URL versions and no support
for header or format versioning.
An API management solution can help
with managing the challenges of GraphQL APIs.
An API management platform gives you
control over and visibility into the APIs that connect
application and data cross-cloud or on-premises.
Managing your GraphQL APIs with an API management platform
enables you to easily manage authentication
and authorization, implement throttling or quotas,
view detailed analytics, and streamline versioning.
To learn more and get started, check out the links
in the description below.
[MUSIC PLAYING]