Anypoint DataGraph Quick Start Guide

Use this quick start guide to begin using Anypoint DataGraph. With Anypoint DataGraph, you can query multiple APIs in a single request to get the specific information you need.

Getting started with Anypoint DataGraph involves:

  1. Downloading and publishing two APIs

  2. Adding those APIs to Anypoint DataGraph and editing their schemas for addition to the unified schema, including how to use various . API schema editing tools like linking and merging

  3. Querying the unified schema

Prerequisites

Before getting started, ensure you have:

  • Familiarity with Anypoint Platform and Exchange, including permissions to use Exchange to publish and view RAML or OAS specifications in your business group

  • An Anypoint Platform account

  • Admin or Contribute permissions

  • The correct number of vCores allocated to your business group or organization using Anypoint DataGraph, as specified in your plan. If you haven’t allocated the correct number of vCores to the environment in which you’re attempting to add an API, Anypoint DataGraph raises an error message.

Download and Publish the Order and Product APIs

To follow the quick-start example, download the RAML definitions for two example APIs provided by MuleSoft: the Order Systems API v2.0 and the Product API v2.0.

  1. Log into Anypoint platform.

  2. In Exchange, click Provided by MuleSoft.

  3. Search for product api raml definition and select it from the list of results.

  4. In the Product API | RAML Definition, click Download > RAML for asset version 2.0.2

  5. Publish the RAML specification to Exchange using your business group ID and an asset name.

    The quick-start example uses the API names Catalyst Product API and Catalyst Order API.

  6. Repeat these steps for the Order Systems API | RAML Definition for asset version 2.0.3.

Add the Catalyst Product API to Anypoint DataGraph

After publishing the example APIs in Exchange, first add the Catalyst Product API to Anypoint DataGraph.

  1. From Anypoint Platform > Anypoint DataGraph, select the appropriate environment from the Unified Data Graph dropdown list, and click +Add API.

  2. On the Select API page, select the Catalyst Product API.

  3. Click Next: Configure URL.

  4. On the Configure URL page, select the API version and asset version, and then select Confirm Selection.

  5. Select Add a new URL.

  6. In the Add URL field, add the following API URL: https://anypoint.mulesoft.com/mocking/api/v1/sources/exchange/assets/68ef9520-24e9-4cf2-b2f5-620025690913/catalyst-retail-product-api/2.0.2/m/

    Adding the API and asset version and URL for the Catalyst Product API

    If your API is managed by API Manager, or if you manually added the URL to Exchange, Anypoint DataGraph retrieves the URL. You can also manually add a new URL if it’s included in the API specification.

  7. Click Save.

  8. Click Next: Provide authentication.

  9. Provide authentication for the GET endpoints for the API (in this quick-start example, No Auth):

    The API authentication is set to No Auth

    Anypoint DataGraph uses these credentials to make requests to this API.

  10. After setting the version and authentication details, click Next: Preview Schema:

    Anypoint DataGraph in API schema preview mode

    Here the specification of the API you’re adding is automatically transformed to its corresponding API schema. You can explore and familiarize yourself with the generated schema before proceeding to the next step.

    For example, you can click through the types to understand the schema hierarchy, or search for a particular element—in this case, price:

    Searching the element price in API schema preview mode
  11. When you’re done previewing the schema, click Next: Edit Schema.

Edit the Catalyst Product API Schema for Addition to the Unified Schema

After you add the Catalyst Product API to Anypoint DataGraph, you:

  • Edit the Schema by Enabling Object Type Collaboration

You don’t have to perform edit functions (enable collaboration, rename, hide/unhide, and link and merge object types) before you add an API schema to the unified schema. You can make changes to an API schema even after you’ve added it to the unified schema. However, you must resolve any conflicts raised by Anypoint DataGraph before adding an API schema to the unified schema.

Edit the Schema by Enabling Object Type Collaboration

When adding APIs to the unified schema, you can configure object types, query methods, and fields to produce more useful query results. More specifically, you can hide or unhide, rename, and link and merge these entities.

However, a crucial step to achieving a connected unified schema is enabling collaboration on object types.

When you enable collaboration on a type, the type provides its fields to other types in the unified schema or in the local API schema, enabling you to create links and merges between types.

To enable collaboration on the ProductResponse object type:

  1. In the Catalyst Product API schema navigation, click the ProductResponse object type.

  2. In the Collaboration permissions pane, click Enable collaboration.

  3. To set the default query method, select productsByProductId (productId:String!): ProductResponse:

    Default query method set to products by product id

    The default query method for an object type is the method that always returns a single record of that object type for which you want to enable collaboration.

  4. Click Next.

  5. To select a primary key, from the dropdown list, select identifier (String!)

    Primary key set to identifier string

    The primary key is one field of your object type that uniquely identifies a single record of that object type.

  6. Click Confirm.

  7. In the Edit type name and field settings pane, make all fields visible.

    When adding an API, all nested types are hidden from the unified schema. This gives you the flexibility to scale the schema according to your needs and make only those types visible that you want to add to the unified schema. Any fields in Level 1 types that return the nested types are also hidden.

  8. Click Next: Add to unified schema.

    Status indicator shows adding API schema to unified schema

    As Anypoint DataGraph updates the unified schema, you can navigate through the schema to view the changes you just made. When the status changes to “Up to date”, indicating that the unified schema has been updated with your changes, proceed to the next step.

Add the Catalyst Order API to Anypoint DataGraph

Follow the same procedure as for adding the Product Order API, with the following exceptions:

  • Use the URL https://anypoint.mulesoft.com/mocking/api/v1/sources/exchange/assets/68ef9520-24e9-4cf2-b2f5-620025690913/catalyst-retail-order-system-api/2.0.3/m/

  • Additionally edit the schema by renaming, linking, and merging the object types that you previously enabled for collaboration.

Edit the Catalyst Order API Schema for Addition to the Unified Schema

After you add the Catalyst Order API to Anypoint DataGraph, you:

  • Edit the Schema by Rename Object Types

  • Edit the Schema by Linking Object Types

  • Edit the Schema by Merging Object Types

You don’t have to perform edit functions (enable collaboration, rename, hide/unhide, and link and merge object types) before you add an API schema to the unified schema. You can make changes to an API schema even after you’ve added it to the unified schema. However, you must resolve any conflicts raised by Anypoint DataGraph before adding an API schema to the unified schema.

Edit the Schema by Rename Object Types

Before you add an API schema to the unified schema, you can edit the schema to rename fields, types, and query methods to make them more intuitive to those consuming the unified schema.

For example, the Catalyst Order API contains a nested type named EnumType0:

Enum type 0 selected in the Catalyst Order API

Anypoint DataGraph generated the name EnumType0 because this enum type was unnamed when added. Because this type provides useful order status information, name it appropriately, to Status.

  1. Click EnumType0.

  2. Switch the Desired state to Visible.

  3. In the Type settings pane, click Rename Type.

  4. Rename the type to Status, and click Confirm.

    Renaming enum type 0 to status in the rename type window

The new name is reflected in the type list.

Edit the Schema by Linking Object Types

You can also edit the unified schema to link your newly added API object types to existing, related types to join fields, resulting in a more enriched query result.

For example, as a result of you adding the Catalyst Product API to it, the unified schema now has product description information that came from the ProductResponse object type. The Catalyst Order API schema also has product information as part of the OrderItemSummary object type. You can link these object types to return results from both in one query.

  1. In the Catalyst Order API schema navigation, select the OrderItemSummary object type.

  2. Because the OrderItemSummary object type and its fields are hidden, use the Hidden/Visible toggle to switch its Desired state value to Visible:

    Setting order item summary visibility desired state to Visible
  3. Scroll to the Link to another type pane, and in Select the type you want to link to (Target), select ProductResponse.

  4. For the foreign key field, set productId (String!):

    The foreign key field in the link configuration is set to product ID string

    The value returned by the foreign key field and the record of ProductResponse it identifies is exactly the same as the primary key of the target ProductResponse object type.

  5. Change the name of the foreign key field from productresponse to product.

    You have the option to hide the foreign key field from the unified schema since the newly added field (product) returns the type you’re linking to. For this example, you can change it to Visible.

  6. Review the new link configuration and click Save changes.

    The OrderItemSummary type is now linked to the ProductResponse! type:

    Order item summary product type field shows the linked icon

You’re almost ready to finish adding the Catalyst Order API. Before you do that, explore another way to edit an API schema before adding it to the unified schema.

Edit the Schema by Merging Object Types

You can merge an object type from your API schema with either another object type in the unified schema or with another object type in the same API schema (known as a local merge). Merging types enables you to combine similar types to extend their fields and datasets for better query results.

In Anypoint DataGraph, there are three merge types:

  • An extension merge, in which merged types join data

  • A reference merge, in which you can retrieve fields only from the target type

  • A composition merge, in which the merged types simplify the unified schema by bringing together types as a single type, but are joined without primary keys

For this example, you perform a local composition merge by merging the OrderSummary object type with the OrderResponse object type:

  1. In the Catalyst Order API schema navigation, select the OrderSummary type.

  2. In the Merge with another type pane, select the type to merge with (in this case, OrderResponseLocal):

    Selecting the target type order response to merge with the order summary type
  3. Use the diff view to get a side-by-side comparison of the two types in the merge, and use the toggle to unhide all the fields.

    The merge diff view shows hidden fields
  4. Click Preview merge result:

    Merge preview results for order summary and order response merge

    The results show that you’re performing a local merge between the OrderSummary and OrderResponse object types. After the merge, the OrderSummary object type is renamed to OrderResponse in the Catalyst Order API schema, and you query the OrderResponse type in the unified schema.

  5. Click Confirm merge.

  6. Click Next: Add to unified schema.

As Anypoint DataGraph updates the unified schema, you can navigate through the schema to view the changes you just made. When the status changes to “Up to date”, indicating that the unified schema has been updated with your changes, proceed to the next step.

Request Access to Query the Unified Schema

After you add the two API schema’s to the unified schema, you’re ready to request permission for access to run a query.

  1. Click Run a query.

  2. Select an access method. For this example, select Create a new application and use it immediately.

    Create a new application is selected in requesting access to run a query window
  3. Click Next.

  4. In the Create a new application window, complete the fields:

    Creating a query application in the request access window
  5. Click Next.

Write a Query

  1. Before writing your query, take a moment to orient yourself to the unified schema. Click Explore Schema.

    The schema explorer is open in the query editor

    Here you can explore the documentation of the unified schema, which is also available through autocompletion as you write your query:

    Using inline autocompletion to write a query
  2. When you’re ready, add the following example query:

    {
      ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") {
        shippingAddress {
          state
          city
          postalCode
        }
        total
        status
        orderItems {
          shipmentItems {
             product {
               model
               description
               brand
               price {
                 amount {
                   name
                   currencyValue
                 }
               }
             }
           }
         }
       }
     }

    Notice that with this one query, you get results from two different APIs:

    Two APIs are being queried from a single query
    1 shippingAddress, total, and status information is returned from the Catalyst Order API
    2 product details is returned as part of the shipmentItems information from the Catalyst Product API

    This is the fundamental utility of Anypoint DataGraph: the ability to query multiple APIs in a single request to get only the information you want.

  3. To run the query without query tracing, click Run:

    Query editor displays query results
  4. To run the query with query tracing, click Trace query > Run.

    Query trace view open with query results

    Trace results for Anypoint DataGraph provide the following information:

    • Time taken by Anypoint DataGraph to parse and validate the query

    • Total response time for the entire query

    • Duration of requests to each source API in the query

  5. To see logs associated with the query, click View response logs.

    Query response logs page

    Log levels for Anypoint DataGraph include DEBUG, INFO, WARN, and ERROR.

    If you have a Titanium subscription, you can view these same logs in Anypoint Monitoring, or use advanced search to find logs for a specific date, time, and priority.

  6. Click View History to access this same query (or others) later. To use this query in an external application, click Copy endpoint to copy both the query and the automatically generated endpoint.

    You can copy the query as a cURL snippet or as a GraphQL query:

    Copying a query endpoint

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub