Author: Ashish Pardhi
Table of Contents
Introduction
Purpose
What is Anypoint Datagraph?
Why do we need Datagraph or GraphQL at all?
Anypoint Datagraph Over HTTP
Unified Schema
Handling Sensitive Data
Auto suggestion in GraphQL WebUI
How to pass Credentials in GraphQL Query?
How to view the history of executed GraphQL Query?
How to trace the GraphQL Query?
How to view the response log for the GraphQL Query?
Anypoint Datagraph HTTP Status Code
Anypoint Datagraph Benefits
Monitoring and Caching
Restrictions And Limitations
Introduction
Purpose
This document will describe an overview of Anypoint Datagraph in the MuleSoft Anypoint Platform. If you’re building a brand new application, starting from zero, putting an Anypoint Datagraph in front of a database will help create minimal architecture.
Similarly, It can be used as a light wrapper around existing APIs if your microservices are already built out.
What is Anypoint Datagraph?
Anypoint Datagraph internally uses GraphQL so we need to understand GraphQL in depth.
GraphQL is a specification for how to talk to an API. It’s typically used over HTTP where the key idea is to POST a “query” to an HTTP endpoint, instead of hitting different HTTP endpoints for different resources.
GraphQL is designed for developers of web/mobile apps (HTTP clients) to be able to make API calls to fetch exactly the data they need from their backend APIs.
Before going further in understanding GraphQL, it’s useful to get a sense of how GraphQL is actually used in an HTTP client.
Use Case:
Let’s start with a use case where a company has a very big business specific application network with data scattered across multiple systems and the company wants to fetch that data in efficient ways. Additional information we have is these systems are unlocked there data via a network of APIs which are internally connected.
As companies build up their network of APIs, it becomes increasingly complex to consume the data needed for each project. Each project needs data in slightly different ways and likely from several APIs at a time. This is hard because the developer has to:
- Write multiple API requests: REST APIs are consumed in request-response mode — making it so you can only ask one API a question at a time. This translates to a request for every API.
- Build custom logic to isolate required fields: REST API responses are complex and return every possible field. The developer will typically write some custom code just to parse the data for their project.
The goal is to reuse multiple APIs at once and get data across multiple APIs at a time, with just one request, and no custom work.
Why do we need Datagraph or GraphQL at all?
With Anypoint DataGraph, you can serve data across multiple APIs instantly. This means less time spent on getting the data across multiple APIs and more time on actual innovation.
To achieve this, you automatically compose a data service by unifying data across APIs into one GraphQL endpoint, without more code. Developers can then act on this data service without understanding the underlying relationships or complexities among different APIs. They can get the data they need for their project from many APIs with a single request.
In this way, Anypoint DataGraph helps you:
Unify APIs into powerful data services
- Explore and unify APIs into data services, without more code
- Serve data from multiple APIs instantly by securely sharing data services
Consume many APIs a single request
- Query the data service with a single, visually built GraphQL schema
- Focus on application logic, without understanding the complexities of the data service
Reach new levels of productivity
- Developers don’t write custom code to parse data from multiple APIs
- Data services are deployed as a SaaS app — no maintenance or patching for IT
Anypoint Datagraph Over HTTP
Let’s say you have an API to fetch a user’s profile and their address. In a typical REST scenario, this is what the request/response would look like:
The core of REST API revolves around resources. Resources are identified by URLs and request type (GET, POST etc.).
Unified Schema
Unified schema holds all the data members of APIs which are added in Anypoint Datagraph. Lets see step by step how to build a unified schema and run it from GraphQL Query.
Step 1: API specification(RAML/OAS) of Mule or Non-Mule Application should be published to Anypoint Exchange.
Step 2: Add these APIs in Unified Schema as follows
1. Goto Anypoint Datagraph
2. Select Environment from the top left corner because Datagraph is an environment specific service then add APIs from Exchange.
a. Click on + Add API option
b. Select API from List
c. Click on Next: Configure URL and Select API Version and Asset Version
d. Click on “Confirm Selection” and Set URL and Save. Here we can use Mocking URL or Implementation URL.
e. Click on “Next: Provide authentication”
f. Only below policies are available for authentication. If you want to pass custom headers then select Custom Headers from the list.
g. Click on “Next: Preview Schema”. Please notice in Preview Schema only Get Methods are added as a Query Methods list that means Anypoint Datagraph only supports Get operation as of now.
h. Click on “Next: Edit Schema”. Here if you want a hide method or any specific sensitive field then toggle the visible button associated with it.
i. Click on “Next: Add to unified schema”. This action will take some time
Step3: Once our Unified Schema status changes from updating to Uptodate the click on the “Run a Query” Option. This action will create an application in Exchange and generate credentials for Datagraph.
j. Client Application got generated in Anypoint Exchange.
k. Click on “Request Access”. This action will validate credentials and allow you to run GraphQL Query.
l. Start running GraphQL Queries now. In the Success scenario Response will have only a “data” element in the JSON response however in the error scenario there will be one more element called “errors”.
Handling Sensitive Data
In Unified Schema we hide or rename the Object field as per the business requirement as below.
In Unified Schema we hide or rename methods as per requirement as below.
Auto suggestion in GraphQL WebUI
In each GraphQL request, while typing we can use CTRL+SPACE to get list of Objects/Resources/fields which are visible equal to true in Unified Schema
How to pass Credentials in GraphQL Query?
Every GraphQL request can have required parameters or credentials.
How to view the history of executed GraphQL Query?
How to trace the GraphQL Query?
How to view the response log for the GraphQL Query?
Logs are kept for 30 days or up to 100 MB. You can see logs for different levels like INFO, DEBUG, ERROR, WARN.
Anypoint Datagraph HTTP Status Code
Every GraphQL request, success or error should return a 200. This is a visible difference compared to REST APIs where each status code points to a certain type of response.
Anypoint Datagraph Benefits
- Avoid over-fetching: You avoid fetching more data than you need because you can specify the exact fields you need.
- Prevent multiple API calls: In case you need more data, you can also avoid making multiple calls to your API. In the case above, you don’t need to make 2 API calls to fetch user and address separately.
- Less communication overhead with API developers: Sometimes to fetch the exact data you need, especially if you need to fetch more data and want to avoid multiple API calls, you will need to ask your API developers to build a new API. With GraphQL, your work is independent of the API team! This allows you to work faster on your app.
- Self-documenting: Every GraphQL API conforms to a “schema” which is the graph data model and what kinds of queries a client can make. This allows the community to build lots of cool tools to explore & visualise your API or create IDE plugins that autocomplete your GraphQL queries and even do “codegen”. We’ll understand this in more detail later!
Monitoring and Caching
With REST APIs and proper HTTP status codes, a simple health check on a given endpoint should give an idea about the API uptime status. A 200 status code means the API is up and running, whereas a 5xx means something is wrong with the server. This isn’t as seamless with GraphQL since the monitoring tool has to parse the response body to see if the server is returning data or error.
With REST APIs, all the GET endpoints can be cached at the server side or using a CDN. They can be cached by the browser as well and bookmarked by the client for frequent invocations. GraphQL doesn’t follow the HTTP spec and is served over a single endpoint, usually (/graphql). Hence the queries cannot be cached in the same way as REST APIs.
However, caching on the client side is better than REST because of the tooling. Some of the clients implementing caching layers (Apollo Client, URQL) make use of GraphQL’s schema and type system using Introspection to allow them to maintain a cache on the client side.
Restrictions And Limitations
There are a few restrictions and limitations for Anypoint Datagraph as follows:
- It preferred to have Primary Keys of Datatypes in String format.
- It supports REST APIs with RAML and OAS specifications.
- It supports GET Methods only.
- It supports upto 250 APIs per Unified Schema.
- It supports Overall upto 16,000 fields per Unified Schema.
- It supports at max 150 concurrent or ongoing calls per Unified Schema.
- Five seconds timeout per call.
- It supports a max 5MB size response per call.
- A 30 Seconds timeout per query.
- At max 100 fields per query.
- Depth of the query can be sixth level at max.
