GraphQL Versus RESTAPI Which is Better for API Observability
API Observability
API providers need to observe their APIs to get meaningful data about whether and how they are consumed in practice. API observability is a form of monitoring that passively logs API traffic to an observability service. Different from traditional API monitoring, with API observability you:
Monitor interactions to improve developer experience Understand how customers use your API Troubleshoot your API
Observing REST APIs is well understood and supported, but not every API is a REST API. In particular, GraphQL APIs behave very differently when it comes to observability. Let’s dive into what that means and how to take advantage of it.
GraphQL APIs Offer Advantages, But Challenge Observability
Many organizations approach API observability by monitoring the endpoints that users access, logging error messages, and measuring the latency of endpoint requests. This strategy is fine for REST APIs, but it is not enough for API observability with GraphQL APIs.
API consumers love GraphQL because it is flexible enough to query data from multiple sources in a single request and handle complex state and cache management, making for a great developer experience.
The benefits from GraphQL aren’t just for API consumers. With GraphQL, API providers can update their APIs without impacting existing queries. Serving data with GraphQL is also platform-agnostic, so API providers can choose the data provider that works best for them including bundling multiple data resources into a single query. Supporting GraphQL is important for API providers committed to building a great developer experience, where queries are efficient, powerful and flexible.
GraphQL’s flexibility is an important benefit for both API providers and API consumers, but this flexibility also means that you need a different approach to observability for GraphQL APIs. Let’s take a deeper look at the challenges that API observability presents in a GraphQL context and how you can handle them so that your organization can observe your GraphQL API.
Observing GraphQL in Practice
To access data from a REST API, a developer calls multiple endpoints separately to patch together all the data that a client needs. For complex apps a GraphQL approach is more appealing because requests to different data sources all happen in a single query. This means that developers only need to request the data that they need when they use GraphQL, whereas REST query structures don’t allow this level of customizable query. For example, a shopping app that displays information about a product, who is selling it, and how long delivery will take, would consist of three separate REST API calls like this:
f
GET /category/
It takes multiple GET calls to receive all the data necessary to load a product page. Data is called from the product endpoint, which returns information including a seller-id. With the seller-id, the app makes a data call to the seller endpoint to get information about the seller, including a location-id. Finally, a call is made to the delivery endpoint with the location-id so that the page knows how long delivery should take for this product. Each response relies on the information from the API call before it, and this approach frequently fetches too much or too little data. A GraphQL call to get only the needed information from multiple sources can be done with a single query:
{
category{
name
product(product-id){
name
productInfo{
size
price
seller-id
}
seller(seller-id){
name
location-id
delivery(location-id){
name
}
}
}
}
}
While the flexibility of a single query for the GraphQL approach is great for developers, this presents a challenge when it comes to monitoring data queries with GraphQL. If there is a partial failure during a transaction with a REST API or if an endpoint fails to return data, the HTTP request returns a failed status response. Both the API provider and the API consumer receive HTTP 500 or 400 errors when a call is unsuccessful and a successful HTTP 200 for successful endpoint calls. A REST API failure from our shopping example would look like this:
HTTP/1.1 400 Unprocessable Entity
{
"error":
{
"code": "400",
"message": "Product ID does not exist"
}
}
With GraphQL, a partial failure will resolve successfully and return HTTP 200 even if the API call didn’t return any of the queried data. The successful HTTP response is a result of the query reaching the server. If the query calls data that doesn’t exist or that the consumer doesn’t have access to, the HTTP response code won’t give you this information. This can make handling errors more difficult because more effort is needed to diagnose errors. API consumers can check the response object for an errors object, which will show which endpoint experienced an error and what caused the error. Here’s what a partial failure would look like in our GraphQL shopping app query example:
{
"errors": [
{ "path": [ "product" ],
"locations": [ { "line": 3, "column": 12 } ],
"extensions": {
"message": "Object not found",
"type": 2
}
}
]
}
An API consumer has the ability to diagnose errors by checking client-side for a GraphQL errors object like the one shown here. Unfortunately, on the server side you may not catch these errors if you aren’t inspecting every call. For API providers to resolve this, they need to monitor the GraphQL payloads their API returns so that they can check for error objects like the developers using their APIs. Monitoring API payloads has the added benefit of letting you know how developers are consuming your API, what queries are most common, which queries have the lowest latency, and whether API consumers are successfully completing queries.
Learn by Observing
An additional benefit to monitoring your GraphQL payloads is that you can log metrics so that you can make long-term decisions about your API based on how developers access it. Logs can tell you which GraphQL queries were successful, who your most loyal users are, which queries first-time users make, and which queries are often bundled together, among other things. This can inform your organization’s customer success strategy, which would allow you to write more effective documentation, find users who are having challenges with their API calls, and offer more proactive support to the developers using your API. With detailed logs, you can get detailed insight into your API. Filtering queries is a powerful technique to aggregate the information from your GraphQL logs.
Aggregating the GraphQL queries to your API then filtering them by categories like field name and argument value will give you actionable information about the majority of the queries being made to your GraphQL API. This tells you what parts of your API are creating the most value for your customers, so you know what to focus on when you write documentation, which queries to reach out to developers about, and which additional features are likely to create value for your users. If your organization has both GraphQL and REST APIs, filtering your queries will allow you to make direct comparisons between how developers use your different APIs.
We’ve covered how your organization should approach GraphQL API observability, and how important it is to an organization that is focused on promoting customer success. While REST API observability can be more intuitive to implement, and there are more existing REST API analytics tools, GraphQL observability has a few unique advantages over REST API observability.
Advantages of GraphQL API Observability
GraphQL queries indicate exactly what information is needed. REST API consumers often underfetch or overfetch data because they can’t choose what specific data they need. GraphQL queries only call the data a consumer needs, which tells you exactly what data is creating value for your consumers. With REST API analytics it can be difficult to determine if multiple successive API endpoint calls are part of a single transaction from your consumer, or if they are unrelated events. GraphQL analytics bundle all the calls needed for a single transaction into a single query, so you know more about how consumers are using your API.
GraphQL API analytics can give you an edge over REST API analytics in product development, and they can make it easier for your organization to focus on customer success. If your organization understands how first-time users are attempting to query your API when they run into challenges, your customer support can play a more active role in resolving the issues your customers run into and therefore offer more detailed and constructive support. If a customer fails to query your API because they call a REST endpoint that no longer exists, your organization may not observe this failure and your customer support won’t be able to reach out to this customer. Contrast this with GraphQL API calls, where queries go to a single endpoint. If a customer tries to query data that no longer exists, your monitoring will record this failure and your customer support can reach out to the user directly to help your customer make successful API calls.
GraphQL has grown very popular over the years, and more teams are choosing to use GraphQL APIs. As an API provider, observing your GraphQL API can be challenging. The vast majority of API analytics tools were built to support REST APIs, and GraphQL is often an afterthought. Moesif is different, built to observe both GraphQL and REST APIs so that your organization can promote customer success and create value for your customers. Moesif provides all of the advantages of GraphQL observability, built-in to the product. You don’t need to forgo powerful analytics tools when you implement a GraphQL API!
Related Articles
API Strategy
Announcing General Availability of the Moesif Developer Portal
We’re thrilled to announce the General Availability of the Moesif Developer Portal, a major leap forward enabling you to deploy a seamless experience for dev...
API Analytics and Monitoring
Introducing AI Explain
We are thrilled to introduce our newest feature to Moesif - AI Explain - a powerful conversational tool that lets you interact with your API analytics data l...
API Analytics and Monitoring
Monitoring Cost and Consumption of AI APIs and Apps
Discover how Moesif can help manage and optimize your AI-driven APIs with powerful observability tools that track costs and usage efficiently.
API Development
Unlock Deep API Insights with Moesif’s HTTP Body Analytics
Learn how to use Moesif to analyze HTTP bodies.
