# mulesoft DataGraph - Full Documentation --- product: DataGraph --- # Adding API Sources to the Unified Schema > For the full documentation index, see: https://docs.mulesoft.com/llms.txt When you add an API, Anypoint DataGraph generates an API schema from that API’s specification, which you can then edit before adding it to the unified schema. Note that some elements in your API specification, such as non-GET operations, are not added to the API schema. See [Errors When Generating the API Schema](https://docs.mulesoft.com/datagraph/troubleshoot-schemas-queries) for more information. Adding an API to the unified schema comprises three tasks: 1. [Add the API to Anypoint DataGraph](#add-the-api-to-anypoint-datagraph) 2. [Preview the generated API schema](#preview-the-generated-api-schema) 3. [Edit the API schema and resolve any conflicts](#edit-the-api-schema-and-add-it-to-the-unified-schema) You must resolve any conflicts between object types before adding the generated API schema to the unified schema. Refer to [Resolve Conflicts](https://docs.mulesoft.com/datagraph/resolve-conflicts) for more information. After you add an API, you can: - [Change its authentication method](#change-the-authentication-method-for-an-api-added-to-the-unified-schema) - [Configure mTLS for the API](#configure-mtls-for-an-api-added-to-the-unified-schema) - [Update its version](#update-an-api-version) > [!NOTE] You can also use the [Anypoint CLI](https://docs.mulesoft.com/datagraph/datagraph-cli) to add and edit API sources in > DataGraph. However, if you add an API source using the CLI, you cannot edit it or update its > version directly in the UI. You must make these changes using the CLI. ## Before You Begin To add an API to the unified schema, ensure you have: - Created a REST API using either a RAML or OAS specification. - Published the API in Exchange in the same organization as your unified schema. DataGraph supports only `stable` state API versions. - Initiated an instance of the API with an accessible URL. The API does not need to be a Mule application or be running on Mule runtime engine or in CloudHub. Additionally you must: - Have [the correct permissions](https://docs.mulesoft.com/datagraph/permissions) to add APIs. - Ensure that the business group or organization using Anypoint DataGraph has the correct number of vCores allocated, 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. ## Add the API to Anypoint DataGraph The first task to adding an API to the unified schema is adding the API to Anypoint DataGraph by configuring its asset version, URL, and authentication method. > [!IMPORTANT] > > - Supported authentication methods to access your API from Anypoint DataGraph are listed in the > following procedure. Any other authentication methods, such as short-lived token methods, are > not supported. See [Supported Authentication Methods](https://docs.mulesoft.com/datagraph/security#supported-authentication-methods) > for more information. 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 API that you want to add. 3. Click **Next: Configure URL**. 4. On the **Configure URL** page, select the API version and asset version of the API you want to add, and then select **Confirm Selection**. 5. Still on the **Configure URL** page, add or edit the API’s URL: - If your API is managed by API Manager or if you have added the API’s instances in Exchange, select **Get an existing URL from Anypoint Platform**. - If you prefer to manually provide your own implementation URL, select **Add a new URL**. 6. Click **Next: Provide authentication**. 7. On the **Configure Security** page, select the type of authentication on the GET endpoints for the API that you are adding: - **No Auth**: Use if your API is public. - **Basic Auth**: Use if you authenticate to your API using a username and password. - **Pass-through**: Use if you authenticate to your API by passing authorization headers. - **Client ID enforcement via headers**: Use if you authenticate to your API passing `client_id` and `client_secret` headers. - **Client ID enforcement via query parameters**: Use if you authenticate to your API passing `client_id` and `client_secret` query params. - **OAuth 2.0 Client Credentials**: Use if you authenticate to your API by passing OAuth 2.0 `client_id`, `client_secret`, and authorization server values. - **Custom**: Use if you authenticate to your API using custom header parameters and values. 8. Still on the **Configure Security** page, optionally add a keystore to configure mutual authentication (mTLS) between the API and DataGraph. Select **Configure Keystore** and provide the following: - A public certificate signed by your organization’s “root” certificate authority (CA) - The private key used to generate the certificate signing request (CSR) - The password for the encrypted private key 9. Optionally, add a truststore to allow your API to be reached by your unified schema. Select **Configure Truststore** and provide the certificate bundle that contains your root CA. 10. Click **Next: Preview Schema**. ## Preview the Generated API Schema After you add the API to it, Anypoint DataGraph automatically translates the API’s specification to its corresponding API schema, which you next preview before editing the schema and resolving conflicts, if any occur: 1. On the **Preview Schema** page, review the types and fields in your API schema. 2. When you’re done previewing the schema, click **Next: Edit Schema**. ## Edit the API Schema and Add It to the Unified Schema The final task in adding an API is to [edit the schema](https://docs.mulesoft.com/datagraph/edit-schema) to resolve conflicts, if any exist, and to enrich the schema. 1. If Anypoint DataGraph has raised an error and prompted you to resolve a conflict, resolve it on the **Edit Schema** page. Conflicts raised by Anypoint DataGraph include suggested resolutions in their prompts. 2. If you want to make the unified schema more robust, edit the API schema (either now or after you add it to the unified schema) to perform the following: - Enable collaboration on an object type. [Enable collaboration](https://docs.mulesoft.com/datagraph/collaboration) for applicable types and provide the required settings. This is optional, but when you enable collaboration on types, you create a more connected and enriched unified schema. - Manage visibility of schema elements. You can [hide the fields, types, or query methods](https://docs.mulesoft.com/datagraph/manage-elements-visibility) that you don’t want visible in the unified schema. - Review and edit names of schema elements. You can [edit the names of all fields, types, and query methods](https://docs.mulesoft.com/datagraph/edit-elements-names) that you add to the unified schema to make them more relevant for queries. - Merge similar object types. [Merging types](https://docs.mulesoft.com/datagraph/manage-merges) enables you to combine similar types to extend their fields and datasets for more enriched query results. - Link related fields between object types. [Linking](https://docs.mulesoft.com/datagraph/manage-links) enables you to join related fields from two types to return a wider range of results when you query the linked types. 3. Click **Next: Add to unified schema**. Anypoint DataGraph [updates the unified schema](https://docs.mulesoft.com/datagraph/status-updates). When the unified schema is updating, you can view the new changes in the schema, make additional changes, and apply new changes. However, these changes aren’t available to query until the update is complete, which can take several minutes. ## Edit the URL for an API Added to the Unified Schema If you need to edit the URL of an API that you’ve added to the unified schema, you can do so on the **API details** page. 1. Click **List of APIs added** and select the API that has the URL you want to edit. 2. Click **API details**. 3. Next to the **API url** field, click **Edit URL**. 4. Type in the new URL. 5. Click **Save**. ## Change the Authentication Method for an API Added to the Unified Schema If you need to edit the authentication method of an API that you’ve added to the unified schema, you can do so on the **API details** page. You must remove the current authentication method and add a new one. To edit the authentication method: 1. Click **List of APIs added** and select the appropriate API. 2. Click **API details**. 3. In the **Authentication** panel, **Click remove and add a new one**. 4. Select an authentication policy and complete any required fields. 5. Click **Save**. ## Configure mTLS for an API Added to the Unified Schema If you need to configure mTLS for an API that you’ve added to the unified schema, you can do so on the **API details** page by adding a keystore. You can also add a truststore to allow your API to be reached by your unified schema. > [!NOTE] If the API already has a keystore or truststore, you can remove either and add new ones on > the **API details** page. To do so, click **Remove and add a new one**. 1. Click **List of APIs added** and select the API that has the URL you want to edit. 2. Click **API details**. 3. Select **Configure Keystore** and provide the following: - A public certificate signed by your organization’s “root” certificate authority (CA) - The private key used to generate the certificate signing request (CSR) - The password for the encrypted private key 4. Optionally, select **Configure Truststore** and provide a link to the certificate bundle that contains your root CA. 5. Click **Save**. ## Update an API Version After you’ve added an API schema to DataGraph, you can update the version of the API source any time you like. DataGraph supports only `stable` state API versions. The update functionality updates only patch and minor versions of an API source. > [!NOTE] If you add an API source using the CLI, you cannot update its version directly in the UI. > You must make these changes using the CLI. When you choose a new version of an API, DataGraph lists any edits you’ve made to the current version that it can’t automatically apply to the new version. For any edits DataGraph can’t automatically apply, you’ll have the option to manually apply these edits before you complete the update. 1. Click **List of APIs added** and select the appropriate API. 2. Click **API details**. 3. From the **Updated Version** list, select the new API version. 4. Click **Next**. 5. If DataGraph finds changes it cannot apply, review the list of **Existing Edits Not Applied in Updated Schema** and manually apply them: 1. Select a customization and click **Next**. 2. Edit the API schema as necessary and click **Apply Changes**. After you apply the changes, repeat Step 5 for any additional changes. 6. Click **Next** to edit the new version’s schema. ## Additional Resources - [Editing API Schemas](https://docs.mulesoft.com/datagraph/edit-schema) - [API Call Scaling in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/api-call-scaling) - [Permissions for Anypoint DataGraph](https://docs.mulesoft.com/datagraph/permissions) - [Configuring Security in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/security) - [troubleshoot-schemas-queries.adoc#potential-errors-when-generating-an-api-schema](https://docs.mulesoft.com/datagraph/troubleshoot-schemas-queries#potential-errors-when-generating-an-api-schema) --- product: DataGraph --- # Anypoint DataGraph API Extension Reference > For the full documentation index, see: https://docs.mulesoft.com/llms.txt This guide defines API extensions for DataGraph. ## Object Type Extensions This extension marks that an object type has a primary key, and thus can be used as a reference or extension. This extension applies to `ObjectType`. ### Structure
FieldTypeDescription

entity

Map

Marks an object type as an entity.

entity.key

String

An array that must not be empty. Each item must reference a field that is a key of the entity.

### OAS Example ```copy components: schemas: Customer: x-entity: key: [id] properties: name: type: string email: type: string id: type: string ... ``` ### RAML Example ```copy types: Customer: (dg.entity): key: [id] properties: name: type: string email: type: string id: type: string ... ``` ## Entity References This extension generates a DataGraph _link_ from the properties of one type to another type. The link can be to a type that is not defined in the same API spec. This extension applies to `ObjectType`. ### Structure
FieldTypeDescription

entity-reference

An array of objects

A list of all the references.

entity-reference.[n].name

String

The name of the type being referenced. May or may not be part of the API.

entity-reference.[n].fieldName

String

The name of the new field that will be created for this type.

entity-reference.[n].keyMapping

Map

The keys of the map represent the fields of this type, and the values represents the keys of the referenced type.

### OAS Example ```copy components: Schemas: Order: x-entity-reference: - name: Customer fieldName: customer keyMapping: customerId: id - name: Store fieldName: store keyMapping: storeId: id properties: orderItems: ... customerId: type: string storeId: type: string Customer: x-entity: key: [id] properties: name: type: string email: type: string id: type: string Store: x-entity: key: [id] properties: name: type: string id: type: string ... ``` ### RAML Example ```copy types: Order: (dg.entity-reference): - name: Customer fieldName: customer keyMapping: customerId: id - name: Store fieldName: store keyMapping: storeId: id properties: orderItems: ... customerId: type: string storeId: type: string Customer: (dg.entity): key: [id] properties: name: type: string email: type: string id: type: string ... Store: (dg.entity): key: [id] properties: name: type: string id: type: string ``` ## Entity Provider This extension marks that an endpoint returns instances of an entity by id. In DataGraph, this is the _default query method_. This extension applies to GET operations. ### Structure The target is not specified because it is implicit in the operation.
FieldTypeDescription

entity-provider

Map

Marks that this endpoint returns entity instances.

entity-reference.keyMapping

Map

The keys of the map represent parameters of this operation, and the values represents the keys of the target type.

### OAS Example ```copy Schemas: Customer: x-entity: key: [id] properties: name: type: string email: type: string 1: type: string ... paths: "/customers/{customerId}": get: x-entityProvider: keyMapping: customerId: id parameters: - in: query name: summaryView default: true schema: type: boolean ... responses: '200': content: application/json: schema: $ref: "#/components/schemas/Customer" ``` ### RAML Example ```copy types: Customer: (dg.entity): key: [id] properties: name: type: string email: type: string id: type: string … /customer/{customerId}: uriParameters: customerId: string get: (dg.entityProvider): keyMapping: customerId: id responses: 200: application/json: body: Customer ``` ## HTTP Method Override Use this extension to treat a POST method as a GET method. This extension converts the POST method into a query operation instead of a mutation. This extension applies to operations. ### Structure The target is not specified because it is implicit in the operation.
FieldTypeDescription

http-method-override

Map

Marks an operation to be overridden.

http-method-override.method

String

The HTTP method that will be used to override the original operation.

### OAS Example ```copy paths: "/customers": post: x-http-method-override: method: get responses: '200': content: application/json: schema: type: array items: $ref: "#/components/schemas/Customer" ``` ### RAML Example ```copy /customers: post: (dg.http-method-override): method: get responses: 200: body: application/json: type: Customer[] ``` ## DataGraph-specific Extensions The main annotation `datagraph` cannot have the same name for different domains. Because of this, the annotations for operations, type, and object properties use postfixes: - Operations: -method - Type: -type - Object properties: -field ### Hide Use this extension to mark an element as hidden. Hidden elements aren’t shown in the unified schema, and DataGraph doesn’t return them in any queries. This extension applies to: - Operations - Any type - Object properties ### Structure The target is not specified because it is implicit in the operation.
FieldTypeDescription

datagraph

Map

A container for DataGraph-specific annotations.

datagraph.hide

Boolean

If true, the element is hidden in the unified schema. If false, the element is not hidden, which provides the same result as not setting the annotation.

### OAS Example ```copy components: Schemas: Customer: x-datagraph: hide: true properties: name: type: string email: type: string x-datagraph: hide: true id: type: string ... paths: "/customers/{customerId}": get: x-datagraph: hide: true parameters: - in: query name: summaryView default: true schema: type: boolean ... responses: '200': content: application/json: schema: $ref: "#/components/schemas/Customer" ``` ### RAML Example ```copy types: Customer: (dg.datagraph): hide: true properties: name: type: string email: type: string (dg.datagraph): hide: true id: type: string … /customer/{customerId}: uriParameters: customerId: string get: (dg.datagraph): hide: true responses: 200: application/json: body: Customer ``` ## Name Use this extension to set the desired name of an element in DataGraph, such as defining specific names for elements in the unified schema. You can also use this extension to federate types from different APIs without changing the underlying APIs. This extension applies to: - Operations - Any type - Object properties ### Structure The target is not specified because it is implicit in the operation.
FieldTypeDescription

datagraph

Map

A container for DataGraph-specific annotations.

datagraph.name

String

The desired name for the element in DataGraph. If possible, use a pattern for valid names.

### OAS Example ```copy components: Schemas: Customer: x-datagraph: name: SalesCustomer properties: name: type: string e-mail: type: string x-datagraph: name: email id: type: string ... paths: "/customers/{customerId}": get: x-datagraph: name: getCustomer parameters: - in: query name: summaryView default: true schema: type: boolean ... responses: '200': content: application/json: schema: $ref: "#/components/schemas/Customer" ``` ### RAML Example ```copy types: Customer: (dg.datagraph): name: SalesCustomer properties: name: type: string e-mail: type: string (dg.datagraph): name: email id: type: string … /customer/{customerId}: uriParameters: customerId: string get: (dg.datagraph): name: getCustomer responses: 200: application/json: body: Customer ``` ## See Also - [Using Anypoint Platform DataGraph CLI and API Extensions](https://docs.mulesoft.com/datagraph/overview-cli-extensions) - [Anypoint CLI DataGraph Command Reference](https://docs.mulesoft.com/datagraph/datagraph-cli) --- product: DataGraph --- # Anypoint DataGraph Best Practices Ruleset > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The DataGraph Best Practices Ruleset is a collection of governance rules you can add as a dependency to any API project you want to use in Anypoint DataGraph. The ruleset is a collection of messages that ensure your API project adheres to DataGraph best practices. The ruleset is publicly available in Exchange and you add the ruleset as a dependency to API specifications in Design Center API Designer. You can also validate an API against the ruleset, using the API Governance CLI. ## Example Use Consider the following `example-api.raml`: #%RAML 1.0 title: DOCS - Order API types: Order: description: An Order properties: orderId: description: The ID of the order type: string additionalProperties: false /orders/{orderId}: get: responses: 200: body: application/xml: type: Order When you apply the DataGraph best practices ruleset, you see the following warning message: example-api.raml (16:3) ⚠️Warning: \[Datagraph Best Practices\] Only JSON payloads are supported at the moment in DataGraph. This is the preferred media type format. This message indicates that `application/xml` in the GET command should be `application/json`. For more information about adding and using rulesets in API Designer, see [Finding API Conformance Issues in API Definitions](https://docs.mulesoft.com/api-governance/find-conformance-issues). --- product: DataGraph --- # Anypoint DataGraph CLI Reference > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Platform provides a command-line interface (CLI) for DataGraph. The CLI supports both the interactive shell and standard CLI modes. Use the DataGraph CLI to manage: - [DataGraph API Sources](#datagraph-api-sources) - [DataGraph Load Balancers](#datagraph-load-balancers) ## Before You Get Started - Review [Using the DataGraph CLI and API Extensions](https://docs.mulesoft.com/datagraph/overview-cli-extensions) before using the CLI to add API sources to DataGraph. - Review [Anypoint CLI prerequisites, installation, and authentication instructions](https://docs.mulesoft.com/anypoint-cli/3.x/). ## DataGraph API Sources
CommandDescription

Adds an API source

Promotes an API source

Updates an API source

Scales API calls made to the unified schema

Downloads the unified schema

Deletes an API source

Gets an API source

Lists all API sources

Returns information about DataGraph

Validates an API source for the unified schema

### datagraph sources add \> datagraph sources add > [!NOTE] DataGraph supports only `stable` state API versions. This command adds an API source, specified by ``, in which `g` is the group ID, `a` the asset ID, and `v` the version ID of the API source. The group ID is optional. If you don’t specify a group ID, the command uses the current organization ID. In addition to the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options, this command accepts the following options:
OptionsDescription

--auth-none

Use if your API is public.

--auth-basic

Use if you authenticate to your API either by passing the basic authentication header or by passing a username and password.

Required:

  • --credentials <username>:<password>

--auth-oauth

Use if you authenticate to your API by passing OAuth 2.0 client_id, client_secret, and authorization server values.

Required:

  • --credentials <client_id>:<client_secret>

  • --server <authorization server URL>

    Not Required:

  • --scope <server>

--auth-pass-through

Use if you authenticate to your API by passing authorization headers.

Required:

  • --mapping: <comma-separated list of key-value pairs, for example, key1:value1,key2:value2>

--auth-headers

Use if you authenticate to your API by passing custom header parameters and values.

Required for headers:

  • --custom-headers: <comma-separated list of header-value pairs, for example, header1:value1,header2:value2>

    Or

  • --custom-headers-file: <location of the file containing header-value pairs, one per line>

--auth-query-params

Use if you authenticate to your API by passing query parameters and values.

Required for query params:

  • --credentials <client_id:client_secret>

--url <url>

Configures the URL for the backend API.

--discover-url

Automatically discovers the URL of the backend API based on the instances running in the current environment. If more than one API is running, DataGraph uses the first URL.

--ca

Specify a comma-separated list of certificate authority (CA) files to add to the API’s truststore, for example, file.ca,file2.ca.

--cert

Specify the filename of the client certificate to use for mutual transport layer security (mTLS), for example, cert.ca.

--key

Specify the filename of the private key to use for mTLS, for example key.pem.

--key-password

Specify the password to decrypt an encrypted private key.

--ignore-invalid-edits

Use to apply valid edits made in the extensions in the API specification and to ignore any edits that are invalid.

> [!NOTE] All headers and query params defined in the command line, and all header and query param > files, are appended. If there are repeated keys, the values provided in the command line takes > precedence. #### Example Command ```copy datagraph sources add 18dc11ee-4a09-4aae-9c6c-4371a87eafa8/product-api/1.0.0/ --url http://test.com ``` #### Example Output { "apiVersion": "v1", "assetId": "product-api", "createDate": "2022-05-20T18:05:41", "endpoint": "http://test.com", "environmentId": "", "groupId": "", "name": "Product API", "organizationId": "", "securityScheme": "NO\_AUTH", "sourceId": "deca7be1-c299-4441-bc7b-dba733e3a11f", "updateDate": "2022-05-20T18:05:41", "version": "1.0.0", "origin": "CLI" } ### datagraph sources promote \> datagraph sources promote This command promotes an API source `` to the target environment ``. In addition to the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options, this command accepts the following options:
OptionsDescription

--auth-none

Use if your API is public.

--auth-basic

Use if you authenticate to your API either by using the basic authentication header or by using a username and password.

Required:

  • --credentials <username>:<password>

--auth-oauth

Use if you authenticate to your API by passing OAuth 2.0 client_id, client_secret, and authorization server values.

Required:

  • --client-credentials <client_id>:<client_secret>

  • --server <authorization server URL>

    Not Required:

  • --scope <server>

--auth-pass-through

Use if you authenticate to your API by passing authorization headers.

Required:

  • --mapping: <comma-separated list of key-value pairs, for example, key1:value1,key2:value2>

--auth-headers

Use if you authenticate to your API by passing custom header parameters and values.

Required for headers:

  • --custom-headers: <comma-separated list of header-value pairs, for example, header1:value1,header2:value2>

    Or

  • --custom-headers-file: <location of the file containing header header-value pairs, one per line>

--auth-query-params

Use if you authenticate to your API by passing query parameters and values.

Required for query params:

  • --credentials <client_id:client_secret>

--url

Configures the URL for the backend API.

--discover-url

Automatically discovers the URL of the backend API based on the instances running in the current environment. If more than one API is running, DataGraph uses the first URL.

--ca

Specify a list of CA files to add to the API’s truststore.

--cert

Specify the client certificate to use for mTLS.

--key

Specify the private key to use for mTLS.

--key-password

Specify the password to decrypt an encrypted private key.

--empty-ca

Deletes all CA certificates.

--empty-mtls

Deletes the client certificate, private key, and private key password information.

> [!NOTE] All headers and query params defined in the command line, and all header and query param > files, are appended. If there are repeated keys, the values provided in the command line takes > precedence. #### Example Command In this example, the `environmentId` is changed after running the `promote` command. ```copy datagraph sources promote d1d27987-939a-4b41-b3ef-411568ee5bdd e7e8da65-9cf1-569e-c9d2-brd2r0rc7rd6 --auth-none ``` #### Example Output { "apiVersion": "1.0", "assetId": "order-e2e", "createDate": "2022-05-27T18:56:03", "endpoint": "http://test.com", "environmentId": "e7e8da65-9cf1-569e-c9d2-brd2r0rc7rd6", "groupId": "", "name": "Order E2E", "organizationId": "", "securityScheme": "NO\_AUTH", "sourceId": "1ff021b3-9296-43fd-9d64-2f9027c25740", "updateDate": "2022-05-27T18:56:03", "version": "1.0.0", "origin": "CLI" } ### datagraph sources update \> datagraph sources update > [!NOTE] DataGraph supports only `stable` state API versions. The `update` command updates only > patch and minor versions of an API source. This command updates the version of an API source ``. In addition to the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options, this command accepts the following options:
OptionsDescription

--auth-none

Use if your API is public.

--auth-basic

Use if you authenticate to your API by passing either the basic authentication header or both a username and password.

Required:

  • --credentials <username>:<password>

--auth-oauth

Use if you authenticate to your API by passing OAuth 2.0 client_id, client_secret, and authorization server values.

Required:

  • --credentials <client_id>:<client_secret>

  • --server <authorization server URL>

    Not Required:

  • --scope <server>

--auth-pass-through

Use if you authenticate to your API by passing authorization headers.

Required:

  • --mapping: <comma-separated list of key-value pairs, for example, key1:value1,key2:value2>

--auth-headers

Use if you authenticate to your API by passing custom header parameters and values.

Required for headers:

  • --custom-headers: <comma-separated list of header-value pairs, for example, header1:value1,header2:value2>

    Or

  • --custom-headers-file: <location of the file containing header-value pairs, one per line>

--auth-query-params

Use if you authenticate to your API by passing query parameters and values.

Required for query params:

  • --credentials <client_id:client_secret>

--url

Configures the URL for the backend API.

--discover-url

Automatically discovers the URL of the backend API based on the instances running in the current environment. If more than one API is running, DataGraph uses the first URL.

--ca

Specify a list of CA files to add to the API’s truststore.

--cert

Specify the client certificate to use for mTLS.

--key

Specify the private key to use for mTLS.

--key-password

Specify the password to decrypt an encrypted private key.

--empty-ca

Deletes all CA certificates.

--empty-mtls

Deletes the client certificate, private key, and private key password information.

--keep-edits

Keeps edits that are present in the current version of the API source instead of extracting those edits from the API specification.

--override-ui-edits

Change the origin of the API source to the CLI. Ff the origin of the API source is the DataGraph UI, use this option to override the UI edits with the edits in the API specification.

--ignore-invalid-edits

Use to apply valid edits made in the extensions in the API specification and to ignore any edits that are invalid.

> [!NOTE] All headers and query params defined in the command line, and all header and query param > files, are appended. If there are repeated keys, the values provided in the command line takes > precedence. #### Example Command The following command updates the URL of the source API and changes its authentication from `auth-none` to `auth-basic`, adding a client ID and secret. ```copy > datagraph sources update b6cb82a6-51dc-4968-861a-aa04447c3442 --url http://test2.com --version 1.0.0 --auth-basic --credentials client-test:client-secret ``` #### Example Output { "apiVersion": "v1", "assetId": "product-api", "createDate": "2022-05-20T18:56:57Z", "endpoint": "http://test2.com", "environmentId": "", "groupId": "", "name": "Product API", "organizationId": "", "securityScheme": "BASIC", "sourceId": "b6cb82a6-51dc-4968-861a-aa04447c3442", "updateDate": "2022-05-27T18:31:39", "version": "1.0.0", "origin": "CLI" } ### datagraph scale \> datagraph scale This command enables you to configure the number of concurrent API calls permitted for a unified schema. Increasing or decreasing API calls enables you to process higher workloads and optimize your consumption when needed. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Command ```copy datagraph scale 300 ``` #### Example Output { "message": "Api calls updated" } ### datagraph schema-download \> datagraph schema-download This command downloads the unified schema for the current environment. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Output directive @key(fields: String) on OBJECT "An Item" type Item { itemId: Int! "A Product" product: OrderProduct! quantity: Int! } "An Order" type Order { items: \[Item!\]! orderId: String! customerId: String! } "A Product" type OrderProduct { productId: String! name: String! } type Query { orders(ordersCount: Int): \[Order!\] ordersByOrderId(orderId: String!): Order ordersProductsByOrderId(productsCounts: Int, orderId: String!): \[OrderProduct!\] } ### datagraph sources delete \> datagraph sources delete This command deletes the specified API source. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Command ```copy datagraph sources delete d40df394-785d-4c91-8aeb-f07568dd57c ``` #### Example Output { "message": "Source deleted successfully", "sourceId": "620afe93-b196-42eb-ae77-b68a0a937b6a" } ### datagraph sources get \> datagraph sources get This command gets the specified API source. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Command ```copy datagraph sources get d1d27987-939a-4b41-b3ef-411568ee5bdd ``` #### Example Output { "apiVersion": "1.0", "assetId": "order-e2e", "createDate": "2022-05-20T16:49:00Z", "hasKeystore": false, "endpoint": "http://test.com", "environmentId": "", "groupId": "", "name": "Order E2E", "organizationId": "", "hasTruststore": false, "securityScheme": "NO\_AUTH", "sourceId": "d1d27987-939a-4b41-b3ef-411568ee5bdd", "updateDate": "2022-05-20T16:49:00Z", "version": "1.0.0", "origin": "CLI" } ### datagraph sources list ```copy > datagraph sources list ``` This command lists all API sources for the current environment. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Output { "apiVersion": "1.0", "assetId": "order-e2e", "createDate": "2022-05-20T16:49:00.000Z", "endpoint": "http://test.com", "environmentId": "", "groupId": "", "name": "Order E2E", "organizationId": "", "securityScheme": "NO\_AUTH", "sourceId": "d1d27987-939a-4b41-b3ef-411568ee5bdd", "updateDate": "2022-05-20T16:49:00.000Z", "version": "1.0.0", "origin": "CLI" }, { "apiVersion": "v1", "assetId": "product-api", "createDate": "2022-05-20T18:05:41.000Z", "endpoint": "http://test.com", "environmentId": "", "groupId": "", "name": "Product API", "organizationId": "", "securityScheme": "NO\_AUTH", "sourceId": "deca7be1-c299-4441-bc7b-dba733e3a11f", "updateDate": "2022-05-20T18:05:41.000Z", "version": "1.0.0", "origin": "CLI" } ### datagraph describe ```copy > datagraph describe ``` This command returns the following information about DataGraph: - `endpoint`: Displays the GraphQL endpoint that accepts requests. - `deploymentError`: If a DataGraph deployment fails, this field describes the error; otherwise, it’s empty. - `deploymentStatus`: Shows whether DataGraph is deploying, running, or has errors. - `logLevels`: Displays a list of the configured log levels. - `envStatus`: Displays the status of the current environment. - `dlbEndpoint`: Displays the load balancer endpoint. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Output { "deploymentStatus": "STARTED", "dlbEndpoint": "datagraph-example.us-e1.prod.cloudhub.io", "endpoint": "datagraph-example.us-e1.prod.cloudhub.io", "envStatus": "STARTED" } ### datagraph validate \> datagraph validate asset This command validates if it’s possible to add an API source to the unified schema. To do so, the command: - Translates the API source into a GraphQL schema. - Validates any API extensions applied in the API specification. - Runs a conflict check against the unified schema. If any of these steps generates a conflict or error, the command returns the result. If it finds no conflicts or errors, it returns a success message. The API source to validate is specified by ``, in which `g` is the group ID, `a` the asset ID, and `v` the version ID of the API source. The group ID is optional. If you don’t specify a group ID, the command uses the current organization ID. This command takes the default `--help`, `-f/--fields`, `-o/--output`, and `--verbose` options. #### Example Command ```copy datagraph validate asset 73b0d8f2-5a2f-4107-884d-fcd80f30bc51/sales-api/1.0.0 ``` #### Example Output { "code": "success" } ## DataGraph Load Balancers
CommandDescription

Adds a dedicated load balancer configuration to Anypoint DataGraph

Displays a dedicated load balancer configuration for Anypoint DataGraph

Removes a dedicated load balancer configuration from Anypoint DataGraph

### datagraph load-balancer-config add ```copy > datagraph load-balancer-config add ``` This command adds a dedicated load balancer configuration specified by `` to Anypoint DataGraph. The `dlbUrl` is a valid URL that includes the DLB domain and the mapping rule `inputUri`. This command accepts only the default options: `--help`, `-f`/`--fields` and `-o`/`--output`. ### datagraph load-balancer-config describe ```copy > datagraph load-balancer-config describe [options] ``` This command displays a dedicated load balancer URL for Anypoint DataGraph. This command accepts only the default options: `--help`, `-f`/`--fields` and `-o`/`--output`. ### datagraph load-balancer-config remove ```copy > datagraph load-balancer-config remove [options] ``` This command removes a dedicated load balancer configuration from Anypoint DataGraph. This command accepts only the default options: `--help`, `-f`/`--fields` and `-o`/`--output`. ## DataGraph CLI Command Errors DataGraph returns these errors when you incorrectly define a command. These errors can be caused by an incorrect option parameter, an ID that cannot be found, or the lack of a required option. - [Options are Required](#options-are-required) - [Not Found](#not-found) - [Bad Request](#bad-request) - [API Already Exists](#api-already-exists) - [No API Instances Found](#no-api-instances-found) - [Must Define URL](#must-define-url) - [Invalid API Calls](#invalid-api-calls) - [Unauthorized](#unauthorized) - [API Not Found in Current Environment](#api-not-found-in-current-environment) ### Options are Required Output: { "error": { "errorMessage": "Options are required" } } Cause: This error indicates that at least one option is required to run the command. - `datagraph sources add`: Either the `--url` option or the `--discover-url` option is required for this command. - `datagraph sources update/promote`: Any available option is required. Define an element to update or promote in the target source. ### Not Found Output: { "errorCode": "dg-xapi-proxy", "errorMessage": "Not Found" } Cause: This error indicates that DataGraph didn’t find the asset. - `datagraph sources add`: The asset is not reachable either because the group ID, asset ID, and version ID does not correspond to a valid asset, or you cannot access the asset. - `datagraph sources update/promote`: The UUID you provided does not exist in the current environment or in the target environment to which you’re attempting to promote the asset. ### Bad Request Output: { "error": { "code": "400", "message": "Bad Request" } } Cause: This error indicates that some required parameters in the command are incorrectly formatted. - `datagraph sources update`: The provided source ID is not a valid UUID. - `datagraph sources promote`: The source ID or the target environment ID are not in a valid UUID format. ### API Already Exists Output: { "errorCode": "dg-federation-source-exists", "errorMessage": "API already exists" } Cause: This error indicates that the API you are trying to add already exists in the unified schema. - `datagraph sources add`: The asset ID and major version of the API source already exist in the unified schema. To make changes to the source, use the `datagraph sources update` command. ### No API Instances Found Output: { "errorCode": "dg-xapi-no-api-instances", "errorMessage": "No API instances found" } Cause: This error indicates the lack of URL to retrieve for an API instance. - `datagraph sources add/update/promote`: This errors appears when using the `` `--discover-url `` option. It occurs when the asset has no valid instances from which the URL can be retrieved that aren’t from a mocking service. In such cases, use the `--url` option instead. ### Must Define URL Output: { "error": { "errorMessage": "Must define url or set --discover-url" } } Cause: This error indicates that you must set the URL using either `--url` or `--discover-url`. - `datagraph sources add`: Because an URL is a required field in the `add` command, you must set one of the two options, `--url` or `--discover-url`. ### Invalid API Calls Output: { "errorCode": "dg-xapi-invalid-api-calls", "errorMessage": "Invalid Api Calls: 1500" } Cause: This error indicates that you requested an invalid number of API calls. - `datagraph scale`: The number of concurrent calls must be a number between 1 and 1200. ### Unauthorized Output: { "error": { "code": "401", "message": "Unauthorized" } } Cause: This error indicates that you lost the session in the CLI when using it in interactive mode. Exit and relaunch the CLI, and then log in again. ### API Not Found in Current Environment Output: { "errorCode": "dg-federation-source-not-in-env", "errorMessage": "API not found in current environment" } Cause: This error indicates that the API source you are trying to edit, delete, or update exists, but it is not in the working environment. - `datagraph sources update/promote`: The UUID sent is not in the working environment. Or, if you are using the `--version` option, the major version is not compatible with the current version. ## DataGraph CLI Validation Errors DataGraph returns these errors when you use the `datagraph validate asset` command before adding or updating an API source against the unified schema. - [Editing Errors](#editing-errors) - [Conflict Errors](#conflict-errors) ### Editing Errors Editing errors are generated when the edits in the particular API source contain a semantic problem. These errors use the code property `dg-federation-customization-conflict` and have the following structure: { "code": "dg-federation-customization-conflict", "detail": \[ { "code": "element-not-found-in-spec", "editType": "set-primary-key", "reason": "field addId was not found in the specification", "element": "Address" } \], "message": "Customization conflict found adding Customer API" } - The `message` field contains a human-readable response of the validation and provides a summary of the error. - The `detail` field contains a list of all the conflicts found in the current asset: - The `code` field identifies the type of error. - The `editType` field identifies the customization that has the conflict. - The `reason` field contains a human-readable description of the issue. - the `element` field contains the problem. ### Conflict Errors Conflict errors occur when you try to add an API schema to the unified schema. These errors use the code property `dg-federation-udg-conflict` and have the following structure: { "code": "dg-federation-udg-conflict", "detail": \[ { "element": "Customer", "violations": \[ { "code": "incompatible-primary-key-set", "keys": \[ "customerId" \], "expectedKeys": \[ "name" \], "message": "Primary key set have edges with different names" } \] } \], "message": "Merge conflict found adding CLI - Customer OAS API" } - The `message` field contains a human-readable response of the validation and provides a summary of the error. - The `detail` field contains a list of all conflicts found when trying to merge the API schema into the unified schema. - The `element` field contains the location of the conflict. - The `violations` field lists the conflicts to fix. - The `code` field identifies the type of the error. - The `message` field contains a human-readable description of the issue, and, depending on the type of error, it can contain additional properties with more details. ## See Also - [Using the DataGraph CLI and API Extensions](https://docs.mulesoft.com/datagraph/overview-cli-extensions) - [Anypoint DataGraph API Extension Reference](https://docs.mulesoft.com/datagraph/api-extensions) --- product: DataGraph --- # Anypoint DataGraph Hosting Options and Networking > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint DataGraph supports the following Anypoint Platform hosting options and network configurations. ## Anypoint Platform Control Plane Hosting Options Anypoint DataGraph is available for US and EU clouds control plane hosting. ## Anypoint Platform Runtime Plane Hosting Options Anypoint DataGraph must connect to the destination URL you provide when adding an API to the unified schema. You don’t need to make any extra configurations on your runtime plane if you meet any of the following scenarios: - Your API implementations run on CloudHub. - Your API implementations run on standalone instances and are connected to an Anypoint Virtual Private Cloud (Anypoint VPC). - Your API implementations run on any runtime plane hosting option and are public. If your API instances run on standalone instances, are not public, and are not connected to Anypoint VPC, you must first pair your standalone runtimes to Anypoint VPC. See [Request Anypoint VPC Connectivity to Your Network](https://docs.mulesoft.com/cloudhub/to-request-vpc-connectivity) for more information. ## Anypoint DataGraph Architecture and Networking Anypoint DataGraph is a fully managed service that runs on Anypoint Platform within the default region of your business group. The following diagram shows the general network architecture for DataGraph: ![General network architecture for Anypoint DataGraph and Anypoint Platform](/mulesoft/current/en-us/datagraph/_images/datagraph-network-architecture.png) Consumer requests from the public internet are routed to Anypoint DataGraph through shared or dedicated load balancers, depending on your CloudHub or Anypoint Virtual Private Cloud (Anypoint VPC) configuration. DataGraph sends requests to the underlying APIs that make up the unified schema. Similarly, when you make changes in the Anypoint DataGraph UI, those changes trigger updates of Anypoint DataGraph in the Runtime Plane. If you’re unable to use port 8082 on a shared load balancer, you must [set a new URL for Anypoint DataGraph to use on a CloudHub dedicated load balancer (DLB)](https://docs.mulesoft.com/datagraph/set-dlb). ## Additional Resources - [Anypoint Platform Hosting Options](https://docs.mulesoft.com/hosting-home/) --- product: DataGraph --- # Anypoint DataGraph Overview > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint DataGraph enables you to unify all the data within your application network in a unified schema. With Anypoint DataGraph you can: - Dynamically query data from a unified schema - Explore your application network from a single UI - Discover, reuse, and serve information from your application network without writing new code ![](https://play.vidyard.com/jh14R8RyB59WPa3QHguJ26.jpg) ## How Anypoint DataGraph Works Every time you add a new API to your application network, Anypoint Platform stores it as a graph of metadata. Anypoint DataGraph enables you to connect those graphs into one _unified schema_ that runs as a single SaaS GraphQL endpoint and contains and links all of the fields defined within all of your APIs. As a result, you can query across the underlying APIs without needing to understand all of the relationships or specific capabilities that exist within them. ### The Unified Schema The unified schema is a single, always-current collection of types from different API schemas that you’ve added to Anypoint DataGraph and made available for consumers to query. The query type in the unified schema contains all the query methods from the different API schemas that you’ve added to DataGraph. Your consumers can access the unified schema to see exactly what data is available to them, all in one place, and request a specific subset of that data in a single query. To help you create a more clean and connected unified schema, Anypoint DataGraph provides three additional functionalities that allow you to: 1. Enable collaboration between object types 2. Link object types to create connections between them 3. Merge object types to combine similar types into a single type to extend their fields and datasets for a more enriched query result ### Example Use Case Consider an organization using the following APIs: - An order API that provides information about specific purchase orders - A shipment API that provides shipment information for each purchase order - A product API that provides product information and specifications The organization wants to create a mobile application to provide specific order status details for its customers. To deliver this mobile application, API developers must build a new API that identifies all orders for a customer, finds the products in those orders, identifies each shipment record, and finds delivery dates and tracking numbers. The enterprise architect must first grant the developers access to each necessary API, and then manage and secure this API after the developers build and deliver it. Now consider that this organization also wants to provide a web application to a warehouse stocking agent for all existing orders of each product, and the web application must also allow stocking agents to return or delete orders. The team would need to go through a similar development to deliver these features. By using Anypoint DataGraph, the organization does not need to create a new API for every new business requirement. The enterprise architect can discover the existing order, shipment, and product APIs and add each API schema to Anypoint DataGraph. Developers can then request access to the unified schema and query the data that they need or update it from a single endpoint. ## Anypoint DataGraph API Support Anypoint DataGraph supports: - REST APIs with RAML and OAS specifications - Up to 250 APIs per unified schema - Up to 16,000 fields per unified schema - A query depth of 100 nested levels - A 30 second timeout per query ## Anypoint DataGraph Administration in API Manager You manage Anypoint DataGraph in API Manager. Typical management tasks include: - Using the [DataGraph Administration settings](https://docs.mulesoft.com/api-manager/latest/datagraph-settings) to view and edit the GraphQL endpoint of a unified schema, configure policies, and configure client providers. - Managing [contracts](https://docs.mulesoft.com/api-manager/latest/datagraph-managing-contracts) to ensure that only authorized client applications can consume the unified schema. - Managing [SLA tiers](https://docs.mulesoft.com/api-manager/latest/datagraph-adding-sla-tiers) for each Anypoint DataGraph instance. - Using the [API Manager Client Applications](https://docs.mulesoft.com/api-manager/latest/datagraph-viewing-application-contracts) page to view and manage client application contracts. ## Anypoint Platform Requirements and Licensing To use Anypoint DataGraph, ensure you meet the following requirements: - You must have a license for each of the following: - Anypoint Platform - API Manager and Analytics - Anypoint DataGraph > [!NOTE] The API calls associated with your Anypoint DataGraph license refer to calls made by > Anypoint DataGraph to downstream REST APIs. - Your plan must allocate the correct number of vCores for your business group or organization using Anypoint DataGraph. 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. Reapply the same changes after allocating the correct number of vCores. Refer to [Anypoint Platform Runtime Plane Hosting Options](https://docs.mulesoft.com/datagraph/hosting-options#anypoint-platform-runtime-plane-hosting-options) for details on API hosting requirements. ## Resources for Getting Started - [Anypoint DataGraph Quick Start Guide](https://docs.mulesoft.com/datagraph/datagraph-qsg) - [Anypoint DataGraph Terminology](https://docs.mulesoft.com/datagraph/datagraph-terms) - [Understanding the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas) - [Writing GraphQL Queries and Mutations in DataGraph](https://docs.mulesoft.com/datagraph/write-queries-tutorial) --- product: DataGraph --- # Anypoint DataGraph Quick Start Guide > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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. Completing this quick start guide involves: 1. Downloading and publishing two APIs 2. Adding those APIs to Anypoint DataGraph 3. Editing their schemas, using various API schema editing tools like linking and merging, for addition to the unified schema 4. Creating a mutation to post data to the unified schema 5. Querying the unified schema to retrieve specific data you posted ## Before You Begin 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 For information, see [DataGraph Permissions](https://docs.mulesoft.com/datagraph/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. > [!IMPORTANT] If you use an Anypoint Virtual Private Cloud (Anypoint VPC), your browser must have > access to the Anypoint VPC to run queries in DataGraph. Without access, you might receive a > `failed to fetch` schema error. To prevent this, > [set up a dedicated load balancer (DLB)](https://docs.mulesoft.com/datagraph/set-dlb). Network and hosting options are described in > [DataGraph Hosting Options and Networking](https://docs.mulesoft.com/datagraph/hosting-options). ## 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](https://anypoint.mulesoft.com/exchange/68ef9520-24e9-4cf2-b2f5-620025690913/catalyst-retail-order-system-api/minor/2.0/console/summary/) and [the Product API v2.0](https://anypoint.mulesoft.com/exchange/68ef9520-24e9-4cf2-b2f5-620025690913/catalyst-retail-product-api/minor/2.0/console/summary/). 1. Log into Anypoint platform. [Take me to Anypoint Platform](https://anypoint.mulesoft.com/login) 2. In Exchange, click **Provided by MuleSoft**. [Take me to Exchange](https://www.mulesoft.com/exchange) 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](https://docs.mulesoft.com/design-center/design-publish#procedure) using your business group ID and an asset name. The quick-start example uses the API project 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, 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 **Add 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 click **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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-configure-api.png) 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: Configure Security**. 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-api-authentication.png) 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-preview-schema.png) 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-preview-search.png) 11. When you’re done previewing the schema, click **Next: Edit Schema**. ## Enable Object Type Collaboration in the Catalyst Product API Schema > [!NOTE] 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. 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-default-query-method.png) 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-primary-key.png) The primary key is one field of your object type that uniquely identifies a single record of that object type. DataGraph also supports object types that use _composite keys_, but this example uses just one primary key. 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-add-api-status.png) As Anypoint DataGraph updates the unified schema, you can navigate through the schema to view the changes you just made. 9. Click **Proceed to unified schema**. ## 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. ## Rename Object Types in the Catalyst Order API Schema 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-rename-type.png) 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 `OrderStatus`. 1. Click **EnumType0**. 2. Switch the **Desired state** to **Visible**. 3. In the **Type settings** pane, click **Rename Type**. 4. Rename the type to `OrderStatus`, and click **Confirm**. The new name is reflected in the type list. ## Link Object Types in the Catalyst Order API Schema You can also edit the unified schema to link your newly added API object types to existing, related types to join fields, which results in a more enriched query result. For example, as a result of adding the Catalyst Product API, 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. If 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-visible-object-type.png) 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-link-configuration.png) 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-link-added.png) 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. ## Merge Object Types in the Catalyst Order API Schema 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-merge-selection.png) 3. Use the diff view to get a side-by-side comparison of the two types in the merge, and if needed, use the toggle to unhide all the fields. 4. Click **Preview merge result**: ![Merge preview results for order summary and order response merge](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-merge-preview-result.png) 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 **Apply Changes**. As Anypoint DataGraph updates the unified schema, you can navigate through the schema to view changes as you make them. When the unified schema status changes to “Up to date”, request access to run queries and mutations. ## Request Access to Run Queries and Mutations After you add the two API schema’s to the unified schema, you’re ready to request permission for access to run an operation. 1. Click **Run Operation**. 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 an operation window](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-request-query-access.png) 3. Click **Next**. 4. In the **Create a new application** window, complete the fields, then click **Next**: ![Creating a query application in the request access window](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-create-query-application.png) 5. Click **Create & Request Access**. ## Explore the Unified Schema 1. Before writing your mutation and query, take a moment to orient yourself to the unified schema. Click **Explore Schema**. ![The schema explorer is open in the query editor](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-explore-schema-docs.png) 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-autocompletion.png) ## Write A Mutation Mutations are operations you use to add, update, and delete data objects. In GraphQL, mutation operations represent the POST, PATCH, PUT, DELETE, and HTTP methods that you’ve defined in your REST API specification. 1. Add the following example mutation: ```copy mutation { createOrdersCustomerByCustomerId( customerId: "1964401a-a8b3-40c1-b86e-d8b9f75b5842", input: { customerId: "1964401a-a8b3-40c1-b86e-d8b9f75b5842", subtotal: "100.21", taxPrice: "15.22", shippingPrice: "10.00", total: "125.43", orderItems: { shipmentItems: [{ orderItemId: "fc3d4900-c5ac-4649-8bc8-cbbef4fe8fde" productId: "e1c515f9-102d-4830-b353-18fe48065732" productName: "Uniforms Modern Fit Short Sleeve Polo Shirt" location: { locationId: "1c9a20dc-c585-42fd-ac1a-1216085b76d2" deliveryMethod: SHIPMENT locationType: PARTNER } price: "50" quantity: 1 }] pickupItems: [{ orderItemId: "88668866-2c6d-4fa6-9e17-4b2c42e0f051", productId: "eb8c8ca7-3c42-4489-a820-3aa138430b75", productName: "Smart Slim Micro Stripe Shirt", location: { locationId: "1c9a20dc-c585-42fd-ac1a-1216085b76d2", deliveryMethod: PICKUP, locationType: STORE }, price: "50", quantity: 1 }], }, shippingAddress: { address: "Street 123", city: "San Francisco", postalCode: "94210", state: "CA", country: "US" }, }) { identifier message } } ``` 2. Click **Run**. DataGraph returns a result that indicates you’ve created a new order: ![A new order is created when you run the example mutation](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-mutation-result.png) ## Write a Query Now you can write a query to retrieve specific information about the order you created. In this case, you can get details about the `shipmentItems`: 1. When you’re ready, add the following example query: ```copy { ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b34") { 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](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-two-apis.png)
1shippingAddress, total, and status information is returned from the Catalyst Order API
2product 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.

2. To run the query without query tracing, click **Run**: ![Query editor displays query results](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-result.png) 3. To run the query with query tracing, from the actions menu (**…​**), select **Trace Query**, and then click **Run**. ![Query trace view open with query results](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-traces.png) 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 4. To see logs associated with the query, from the actions menu (**…​**), click **View Response Logs**. ![Query response logs page](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-response-logs.png) Log levels for Anypoint DataGraph include DEBUG, INFO, WARN, and ERROR. You can view these same logs in Anypoint Monitoring (Anypoint Integration Advanced package or Titanium subscriptions only) , or use advanced search to find logs for a specific date, time, and priority. 5. Click **View History** to access this same query (or others) later. 6. To copy the query and the automatically generated endpoint, from the actions menu (**…​**​), click **Copy & Share Endpoint**. Use the copy-to-clipboard icons to copy the query as a cURL snippet or as a GraphQL query. You can also copy any authentication values, request headers, or variables used in the query. ## See Also - [Anypoint DataGraph Terminology](https://docs.mulesoft.com/datagraph/datagraph-terms) - [Understanding the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas) - [Writing GraphQL Queries and Mutations in DataGraph](https://docs.mulesoft.com/datagraph/write-queries-tutorial) --- product: DataGraph --- # Anypoint DataGraph Release Notes > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The following release notes are provided for Anypoint DataGraph: - [Anypoint DataGraph Release Notes](https://docs.mulesoft.com/release-notes/datagraph/anypoint-datagraph-release-notes) - [Known Issues](https://help.salesforce.com/s/issues) --- product: DataGraph --- # Anypoint DataGraph Terminology > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The following terms, some of which come from the GraphQL lexicon, are useful for understanding how Anypoint DataGraph works.
TermUsage

API schema

Generated by Anypoint DataGraph from your API specification in RAML or OAS, an API schema contains a collection of the GET resources and entities that you’ve defined in your API specification, and the relationships between them.

Unified schema

The unified schema is a single, always-current collection of types from different API schemas that you’ve added to Anypoint DataGraph and made available for consumers to query.

Object types

The most common type in a schema, object types represent entities in your API specification that are returned as part of a GET response.

Enum types

An enum type returns only a specific set of values that you’ve defined in your API specification.

Union types

Union types describe instances of data using other object types. A union type consists of one or more specific object types.

Query types

A query type is the entrypoint to an API schema when you make a request. This type contains the query methods you’ve defined in your API specification.

Query methods

Each unique GET endpoint defined in your API specification is represented by a query method, which you use to start a query.

Fields

Fields are properties you define for an object type in your API specification.

Level-1 types

In an API schema, Level-1 types are object types that can be directly returned by a query method.

Nested types

In an API schema, you can access nested types only through the query methods of Level-1 types. Nested types are not directly returned by a query method.

Collaboration

By enabling collaboration on Level-1 object types, you allow other types to link and merge with such types. Collaboration enables you to create a more connected unified schema so that your consumers can have a more efficient query experience.

Collaboration is possible only on Level-1 object types.

Linking

Linking enables you to join fields from two related types that describe different objects to create a connection between them.

Merging

Merging types enables you to combine similar types into a single type and extend their fields and datasets for an enriched query result.

## Additional Resources - [Understand the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas) - [Run Queries and Mutations](https://docs.mulesoft.com/datagraph/query-unified-schema) --- product: DataGraph --- # Anypoint DataGraph Troubleshooting > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The following topics provide useful information for troubleshooting in DataGraph: - [Troubleshooting Runtime Errors](#troubleshooting-runtime-errors) - [Troubleshooting Schema Errors](#troubleshooting-schema-errors) - [Troubleshooting mTLS Errors](#troubleshooting-mtls-errors) - [Troubleshooting Access Errors](#troubleshooting-access-errors) - [Troubleshooting Server Errors](#troubleshooting-server-errors) ## Troubleshooting Runtime Errors If you encounter runtime errors when attempting to use the Anypoint DataGraph query editor, troubleshoot them as follows. ### Failed to Fetch Schema Error A failed to fetch schema error occurs when you navigate to the Anypoint DataGraph query editor and it displays the following: { "message": "Failed to fetch", "stack": "TypeError: Failed to fetch" } Anypoint DataGraph generates this error when it cannot load the unified schema, and it occurs for one of three reasons: 1. You’re unable to use Port 8082 on a shared load balancer. Solution: Create a dedicated load balancer (DLB) and [set its URL to configure Anypoint DataGraph to route requests through the DLB](https://docs.mulesoft.com/datagraph/set-dlb). 2. You’ve set a DLB using an invalid certificate. Solution: Ensure that your DLB has a valid, CA-signed certificate, or the browser won’t connect to Anypoint DataGraph. 3. Your internet browser is unable to access Anypoint Virtual Private Cloud (VPC). Solution: Ensure that you can connect to Anypoint VPC from your internet browser. Refer to [Anypoint DataGraph Architecture and Networking](https://docs.mulesoft.com/datagraph/hosting-options#anypoint-datagraph-architecture-and-networking) for an overview of Anypoint DataGraph networking. ### Exception While Fetching Data Error After you run a query, Anypoint DataGraph displays an error similar to the following: { { "errors": \[ { "message": "Exception while fetching data (/ordersById) : Error 429 executing request.", "locations": \[ { "line": 2, "column": 3 } \], "path": \[ "ordersById" \], "extensions": { "httpResponse": { "statusCode": 429, "xHeaders": { "x-ratelimit-limit": 10 "x-ratelimit-remaining": 0 "x-ratelimit-reset": 41827 "x-xss-protection": "1; mode=block" }, "contentType": "application/json", "body": { "error": "Quota has been exceeded" } }, "classification": "DataFetchingException" An exception while fetching data error occurs when the unified schema can’t connect to its underlying APIs. To troubleshoot this error, ensure that: 1. The underlying APIs are running. 2. The URL provided for each API is correct. Go to **List of APIs added** > Select an API > **API details**, and confirm the URL. 3. You [must request connections](https://docs.mulesoft.com/cloudhub/to-request-vpc-connectivity) for any of your APIs that run on standalone instances that aren’t connected to Anypoint VPC. 4. You check the `extensions` section of the error message for any details that may be useful in troubleshooting the error. ### Other Runtime Errors - Can’t prettify an invalid query If you attempt to prettify an invalid query, DataGraph generates a syntax error. To resolve the issue, correct the syntax and then prettify the query. - Invalid action error If you perform an action in the DataGraph editor that creates an invalid schema, DataGraph generates an error. If you believe the action is valid, contact MuleSoft support. ## Troubleshooting Schema Errors If you encounter runtime errors when attempting to generate an API schema, troubleshoot them as follows. ### Potential Errors When Generating an API Schema When you add a new API to your unified schema, Anypoint DataGraph generates an API schema for it. However, not all features of an API specification are successfully generated into an API schema. Anypoint DataGraph does not translate the following parts of an API specification into an API schema: - Requests with a `Media type` value other than `application/json` - Responses with a `Media type` value other than `application/json` - Response payloads with any of the unsupported types `Schema`, `File`, `Tuple`, `Matrix`, `Nil`, or arrays of any of the types - `query params` and `headers` with types other than scalars or scalar arrays - Endpoints of required `params` of unsupported types - `union` types with members other than `objects` and `nils` - JSON schema keywords `if`, `then`, and `else` If your API specification is composed of only unsupported parts, Anypoint DataGraph does not generate an API schema and throws a `Validation failed` error. ## Troubleshooting Errors When Adding, Updating, or Promoting APIs If you encounter errors when adding, updating, or promoting APIs, troubleshoot them as follows: - Two users updated an environment at the same time error If two users attempt to update an environment at the same time, DataGraph generates an error for one of the users. If you receive the error, wait for any updates to complete and again. - Issue with action performed while editing an API error If you receive this error, try adding the API without editing to see if the edit actions created the problem. - Not enough capacity to deploy error DataGraph generates this error if your environment does not have the capacity available to create the unified schema. If you receive this error, request more capacity from your admin, or ask your operator to redistribute capacity within the organization. ## Troubleshooting mTLS Errors If you encounter mTLS errors, troubleshoot them as follows: - Uploading a file that cannot be read error This errors indicates that you uploaded a certificate file that is not in `.pem` format. Ensure the file is a valid `.pem` file and upload it again. - Trying to validate an invalid keystore error DataGraph generates this error if the private key or password does not match the certificate. Ensure the private key and certificate match or confirm the password. - Issue with TLS error This error occurs when trying to configure mTLS for an API that you’ve added to the unified schema. To troubleshoot this issue, add the API without configuring mTLS to determine if there is a problem with your TLS files. ## Troubleshooting Access Errors If you encounter errors when trying to access DataGraph, troubleshoot them as follows: - Access request not approved yet error If you encounter this error, request access from your admin. - Unauthorized error If you encounter this error, request authorization from your admin. - Too many requests error DataGraph generates this error if you attempt too many requests. In this case, wait some time and try your request again. ## Troubleshooting Server Errors If you encounter server errors, troubleshoot them as follows: - Server error when creating policies, contracts, tiers, and grant types If you encounter a server error when creating policies, contracts, tiers, or grant types, wait a few minutes and try again, or check the status of API Manager. - Server error when selecting asset If you encounter a server error when selecting an asset to create policies, wait a few minutes and try again, or check the status of Exchange. ## See Also - [Troubleshoot Queries With Response Logs](https://docs.mulesoft.com/datagraph/troubleshoot-query-logs) - [Troubleshoot Query Performance with Query Tracing](https://docs.mulesoft.com/datagraph/troubleshoot-query-traces) - [Resolving Conflicts and Merge Inconsistencies](https://docs.mulesoft.com/datagraph/resolve-conflicts) - [Known Issues](https://help.salesforce.com/s/issues) --- product: DataGraph --- # Configuring Security in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You must set up authentication so Anypoint DataGraph can access the GET endpoints of the APIs that you add to the unified schema. Authentication allows DataGraph to make requests to those APIs when you run queries. Optionally, you can also set up mutual authentication (mTLS) between your APIs and DataGraph. ## Supported Authentication Methods When adding a new API schema to the unified schema, or when promoting an API schema to another environment, you must configure one of the following authentication methods: - **No Auth** Use if your API is public. - **Basic Auth** Use if you authenticate to your API using the basic authentication header, or a username and password. For example: ```CURL curl "http://localhost/myResource" -u myUser:myPassword ``` or ```CURL curl GET 'http://localhost/myResource' \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "myUser", "password": "myPassword" }' ``` - **Pass-through authentication** Use if you authenticate to your API by passing authorization headers. You must supply: - A **Query Header Name**: The name of the HTTP header sent with the initial query to the unified schema. - An **API Header Name**: The header name passed through to the underlying API. This is useful if you want to rename the query header before passing it through to the underlying API. - **Client ID enforcement via headers** Use if you authenticate to your API by passing `client_id` and `client_secret` headers. For example: ```CURL curl "http://localhost/myResource" -H "client_id:1234" -H "client_secret:abcd" ``` - **Client ID enforcement via query parameters** Use if you authenticate to your API by passing `client_id` and `client_secret` query params. For example: ```CURL curl "http://localhost/myResource?client_id=1234&client_secret=abcd" ``` - **OAuth 2.0 Client Credentials** Use if you authenticate to your API by passing OAuth 2.0 `client_id`, `client_secret`, and authorization server values. For example: ```CURL curl --request POST \ --url 'https://YOUR_DOMAIN/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data 'grant_type=authorization_code&client_id=YOUR_CLIENT_ID&code_verifier=CODE_VERIFIER&code=AUTHORIZATION_CODE&redirect_uri=https://YOUR_APP/callback' ``` - **Custom** Use if you authenticate to your API using custom header parameters and values. Any other authentication methods to access your added API, such short-lived token methods, are not supported. ## Configuring Mutual Authentication in DataGraph Mutual authentication (mTLS) ensures that Datagraph and the underlying APIs in your unified schema can create secure, verified connections. If an API requires mTLS, configure mTLS when adding the API to the unified schema or when promoting the API to another environment. To do so, provide the following: - A keystore that contains: - A public certificate signed by your organization’s root certificate authority (CA) - The private key used to generate the certificate signing request (CSR) - The password for the encrypted private key Optionally, to allow your API to be reached by your unified schema, you can add a truststore and provide the certificate bundle that contains your root CA. Anypoint Platform stores the keystore and the truststore in PEM files in the [Secrets Manager](https://docs.mulesoft.com/anypoint-security/index-secrets-manager). > [!NOTE] If you enable mTLS for an API with a self-signed certificate, DataGraph won’t be able to > establish a TLS connection with that API. ## Configure mTLS for an API Added to the Unified Schema If you need to configure mTLS for an API that you’ve added to the unified schema, you can do so on the **API details** page by adding a keystore. You can also add a truststore to allow your API to be reached by your unified schema. > [!NOTE] If the API already has a keystore or truststore, you can remove either and add new ones on > the **API details** page. To do so, click **Remove and add a new one**. 1. Click **List of APIs added** and select the API that has the URL you want to edit. 2. Click **API details**. 3. Select **Configure Keystore** and provide the following: - A public certificate signed by your organization’s “root” certificate authority (CA) - The private key used to generate the certificate signing request (CSR) - The password for the encrypted private key 4. Optionally, select **Configure Truststore** and provide a link to the certificate bundle that contains your root CA. 5. Click **Save**. ## Additional Resources - [Adding API Sources to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema) - [Promoting API Schemas](https://docs.mulesoft.com/datagraph/promote-api) - [Change the Authentication Method for an API Added to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema#change-the-authentication-method-for-an-api-added-to-the-unified-schema) --- product: DataGraph --- # Creating and Editing Links Between Object Types > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The following tasks explain how to create and undo links between object types. ## Link Related Object Types Linking enables you to join fields from two related object types to create more useful query results from the unified schema. - Before linking object types, be sure to [set the fields to visible](https://docs.mulesoft.com/datagraph/manage-elements-visibility). - You can link only to object types that have [Enable collaboration](https://docs.mulesoft.com/datagraph/collaboration#enable-collaboration-on-an-object-type)for any object types you want to link to. To link object types: 1. In the API schema navigation, select the object type you want to link from (source). 2. Scroll to the **Link to another type** pane, and in **Select the type you want to link to (Target menu)**, select the target object. Anypoint DataGraph detects and displays the primary key or the composite keys of the target type. 3. Use the drop-down menu to select the field that will be the foreign key in the source. The foreign key maps to the primary key on the target type and has the exact same data type. If the target type uses composite keys, you must select two fields. 4. In **New field configurations**, review and edit, if necessary, the name for the linked field. Anypoint DataGraph creates this field in your current type and links it to the target type. 5. (Optional) Hide the foreign key field from the unified schema. The new field returns the type you’re linking to, so it’s safe to hide the foreign key unless it has outstanding queries. ![Link configurations detailing linked target type results](/mulesoft/current/en-us/datagraph/_images/link-object-type.png) 6. Click **Save changes**. If you scroll up to the fields pane, an icon shows the fields are now linked: ![Linked object indicated by link icon](/mulesoft/current/en-us/datagraph/_images/linked-type-icon.png) ## Remove a Link Between Object Types A field can be linked to only one other object type at a time. So if you no longer need the link, or want to link the field to another object type, you can remove the original link. To remove a linked between object types: 1. From the unified schema, click **List of APIs added** and select the API that contains the object type with the linked field. 2. In the API schema navigation, select the object type with the linked field, and scroll to the **Link to another type** pane. 3. Find the link you want to remove and click **\>** to open the link details. 4. Click **Remove Link**. 5. Click **Save**, and then click **Apply Changes**. ## Additional Resources - [How Links Between Object Types Work in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/linking) --- product: DataGraph --- # Creating and Editing Object Type Merges > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The following tasks explain how to create and undo merges within the unified schema and within the local schema. ## Merge Object Types Merging object types enables you to combine the fields of two similar object types and create more valuable results from a single query. You can merge object types locally within the same API schema, or merge an object type with a type in the unified schema. Ensure object types you want to merge are [set to visible](https://docs.mulesoft.com/datagraph/manage-elements-visibility). To merge object types: 1. In the API schema navigation, select the object type you want to merge. 2. In the **Merge** pane, select the target type to merge with. The following example merges the current type, called **OrderSummary**, with a target object type called **OrderResponse**: ![Selecting the target type order response to merge with the order summary type](/mulesoft/current/en-us/datagraph/_images/merge-selection.png) The target type does not need to have the same name. 3. If the current type allows collaboration but collaboration is not yet enabled, and if the selected target type has a primary key defined, make one of the following selections: - (Recommended) Join fields from the two types to have a more enriched query result for this type. If you make this selection, you are taken to the **Enable collaboration** pane, where you set a default query method and a primary key, or two primary keys if the query method uses composite keys. (Refer to [Enable Collaboration on a Type](https://docs.mulesoft.com/datagraph/collaboration) for more information about object type collaboration.) - Declare the current type as a reference so that it returns only the fields and dataset of the type it’s merged with. 4. In the **Merge with another type** pane, click **Preview merge** results. In the following example, the preview shows the target **OrderResponse** object type in the unified schema, including the new fields added after the **OrderSummary** object type is merged with **OrderResponse**: ![Merge preview results for order summary and order response merge](/mulesoft/current/en-us/datagraph/_images/merge-preview.png) 5. To finish, click **Confirm merge**: After you apply your changes, the resulting object type in the unified schema indicates the merge, as shown: ![Merge preview results indicator](/mulesoft/current/en-us/datagraph/_images/merged-type-results.png) ## Undo Merges Between Object Types You can undo merges between object types as needed. For example, if you want to merge Object Type A with Object Type C, but Type A has already been merged with Type B in the unified or local API schema, you must undo the existing merge between Types A and B before creating a new merge with Type C. Note the following: - Undoing a merge will break existing queries of the merged type. - If you undo a merge between Object Type A and Type B in the unified schema, you must rename Object Type A (and its query method, if merged). Anypoint DataGraph displays a conflict until Object Type A (and its query method) are renamed or merged again with Type B. - Nullable fields return to their original state after you undo a merge. For example, if a field in an object type was non-nullable, but as a result of a merge became nullable, then the field returns to being non-nullable after you undo the merge. To undo a merge: 1. From the unified schema, click **List of APIs added** and select the API that contains the merged object type. 2. In the API schema navigation, select the object type and scroll to the **Merge** pane. 3. Click **Undo merge**. 4. Click **Apply Changes**. ## Split a local merge Split local merges to resolve conflicts, manage element visibility, rename fields, or perform other edits on your local API schema. If you have object types that are merged locally and merged with a type in the unified schema, you’ll first need to undo the merge with the unified schema. To split a merge: 1. Click **List of APIs added** and select the API schema that contains the object type to unmerge. 2. In the API schema navigation, select the object type and scroll to the Merge pane. 3. Click **Split Local Merge** > **Apply Changes**. After the split, the types return to their original states but retain any customizations, such as field visibility changes or new names. ## Additional Resources - [Resolve Conflicts and Merge Inconsistencies](https://docs.mulesoft.com/datagraph/resolve-conflicts) - [How Object Type Merges Work in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/merge-types) --- product: DataGraph --- # Editing API Schemas > For the full documentation index, see: https://docs.mulesoft.com/llms.txt When adding a new API to the unified schema, you must edit the schema to make sure that none of the types in your current schema conflict with existing types in the unified schema. Each type in the unified schema must be unique. You don’t have to perform edit functions 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, if Anypoint DataGraph raises any conflict errors, you must edit your schema to resolve those conflicts _before_ adding it to the unified schema. > [!NOTE] If you add an API source using the CLI, you cannot edit it or update its version directly > in the UI. You must make these changes using the CLI. To edit an API schema, address the following tasks where applicable: - Resolve any conflicts between object types If there are types that have a conflict with the unified schema, make sure to resolve them all. See [Resolving Conflicts and Merge Inconsistencies](https://docs.mulesoft.com/datagraph/resolve-conflicts) for more information. - Enable collaboration on an object type Enable collaboration for applicable types and provide the required settings. This step is optional, but when you enable collaboration on types, you’ll create a more connected and enriched unified schema. Refer to [Enabling Object Type Collaboration in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/collaboration) for more information. - Manage visibility of schema elements You can hide the fields, types, or query methods that you don’t want to have visible in the unified schema. Refer to [Schema Element Visibility in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/manage-elements-visibility) for more information. - Review and edit names of schema elements You can review or change the names of all fields, types, and query methods that you are adding to the unified schema. Refer to [Editing Names of Schema Elements](https://docs.mulesoft.com/datagraph/edit-elements-names) for more information. - Merge similar object types Merging types enables you to combine similar types to extend their fields and datasets for a more enriched query result. Refer to [How Object Type Merges Work in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/merge-types) for more information. - Link related fields between object types Linking enables you to join related fields from two types for a more enriched query result. Refer to [How Links Between Object Types Work in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/linking) for more information. - Edit an API URL If you need to edit the URL of an API that you’ve added to the unified schema, you can do so on the **API details** page. Refer to [Edit the URL for an API Added to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema#edit-the-url-for-an-api-added-to-the-unified-schema). - Change the Authentication Method for an API If you need to edit the authentication method of an API that you’ve added to the unified schema, you can do so on the **API details** page. Refer to [Change the Authentication Method for an API Added to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema#change-the-authentication-method-for-an-api-added-to-the-unified-schema). - Configure mutual authentication (mTLS) for an API If you need to configure mTLS for an API that you’ve added to the unified schema, you can do so on the **API details** page. Refer to [Configure mTLS for an API Added to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema#configure-mtls-for-an-api-added-to-the-unified-schema). - Update an API version After you’ve added an API schema to DataGraph, you can update the version of the API source any time you like. Refer to [Update an API Version](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema#update-an-api-version). --- product: DataGraph --- # Editing Names of Schema Elements > For the full documentation index, see: https://docs.mulesoft.com/llms.txt When you add APIs to the unified schema, can rename fields, types, and query methods so they’re more useful to those consuming the unified schema, or so you can resolve conflicts between elements. If you attempt to rename a type in an API that is merged with a type in the unified schema, you will undo the merge. Likewise, modifying the name of a field that you’ve configured as a primary key will break the link or merge associated with that primary key. When renaming fields or query methods, ensure that you are not breaking existing collaborations on those elements. Before editing the name of an element, be sure to [make it visible](https://docs.mulesoft.com/datagraph/manage-elements-visibility). To edit the name of a schema element: 1. Navigate to object type, field, or method, and click **Rename**. 2. In the **Change to:** field, add the new name, and click **Confirm**. 3. If you want to reset to the element to its default, click **Rename** again, and then click **Reset name to default**. --- product: DataGraph --- # Enabling Object Type Collaboration in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Enabling collaboration on a Level-1 object type allows you to achieve a connected and enriched unified schema. When you enable collaboration on a type, you allow similar types in your API schema or in other API schemas to collaborate with your type and directly add their own fields. The result is an extended list of fields and dataset, resulting in a more enriched query result for this type. 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 between types See [Link Types](https://docs.mulesoft.com/datagraph/linking) for more information. - Merge types with other types See [Merge Types](https://docs.mulesoft.com/datagraph/merge-types) for more information. You can enable collaboration only on Level-1 object types: those directly returned from a query method. See [Level-1 and Nested Types](https://docs.mulesoft.com/datagraph/schemas#level-1-and-nested-types) for more information. To successfully understand the requirements for enabling collaboration, you must be familiar with the types in your API schema. See [Understanding the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas) for more information. ## Default Query Method and Primary Keys To enable collaboration on a type, you must configure a default query method and one or two primary keys for that type to access its fields. The default query method for an object type is the method that returns a single record of that object type for which you want to enable collaboration. You can select a query method as the default only if: - It has one or two required input arguments. - The input argument is a scalar data type (`Int`, `Float`, `String`, `Boolean`, or `ID`). The primary key is one field of your object type that uniquely identifies a single record of that object type. For a field to be a primary key, it must be visible and it should be non-nullable (represented by a `!` sign at the end). If the query method uses two primary keys, those are _composite keys_. For example, to enable collaboration on the Order type of the following API schema: ```none ordersById (id: ID!): Order -------------------- -------------------- Order -------------------- orderId: ID! date: String status: String ``` In this example, the default query method is `ordersById`, and its primary key is `orderId`. `ordersById` retrieves the `Order` type and uses `orderId` to retrieve specific information based on the `ID` field. Note that the data type of the default query method’s input argument `ID` must be the same as the data type of the primary key. In this example, both are of data type `ID!`. ### Default Query Method with Composite Keys In the following example using composite keys, the default query method is `productDetail` and its composite keys are `productId` and `productSku`. Both retrieve the `Product` type and use `productId` and `productSku` to retrieve specific information based on the `string` fields. Note that the data type of the default query method’s input arguments must be the same as the data type of each primary key. In this example, both are of data type `string!`: ```none productDetail (id: String!, sku: String!): Product -------------------- -------------------- Product -------------------- productDetail: string!, string! productId: String productSku: String ``` ## Enable Collaboration on an Object Type 1. In the API schema navigation, select the Level-1 object type for which you want to enable collaboration. 2. In the **Collaboration permissions** pane, click **Enable collaboration**. 3. Set the default query method. The following image shows a query method that uses two mandatory arguments. ![A default query method that uses composite keys](/mulesoft/current/en-us/datagraph/_images/composite-keys-default-query-method.png) 4. Click **Next**. 5. Depending on your query method, select one or two primary keys. The following image shows composite keys since the query method uses two mandatory arguments. ![Two primary keys are selected](/mulesoft/current/en-us/datagraph/_images/composite-keys.png) ## Disable Collaboration for an Object Type If you no longer want an object type to provide its fields to other types, you can disable collaboration for that type. However, if you disable collaboration on an object that is merged with another object type in the unified schema, the merge breaks and creates a conflict that you must resolve. To disable collaboration: 1. Click **List of APIs added** and select the API that contains the object type for which you want to disable collaboration. 2. In the API schema navigation, select the object type. 3. In the **Collaboration permissions** pane, clear the selection for **Allow collaboration for this type (Extend this type).** 4. When prompted, confirm that you want to disable collaboration for the object type by clicking **Undo merge and disable collaboration**. 5. If a conflict occurs, follow the prompts in Anypoint DataGraph to resolve it. --- product: DataGraph --- # Getting Started With Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Use the following documentation to learn about key concepts and get started with Anypoint DataGraph. - [Anypoint DataGraph Quick Start Guide](https://docs.mulesoft.com/datagraph/datagraph-qsg) Use this quick start guide to begin using Anypoint DataGraph. - [Anypoint DataGraph Terminology](https://docs.mulesoft.com/datagraph/datagraph-terms) Learn key terms that are useful for understanding how Anypoint DataGraph works. - [Understanding the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas) Understand the different types that can be present in your API schema depending on your API specification. - [Writing GraphQL Queries and Mutations in DataGraph](https://docs.mulesoft.com/datagraph/write-queries-tutorial) This brief tutorial introduces key concepts for writing GraphQL queries in Anypoint DataGraph. --- product: DataGraph --- # How Links Between Object Types Work in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can link your current object type to a different target object type to improve the query experience. Linking enables you to join fields from two related types that describe different objects and create a connection between those types. You can link your current object type to a target object type if your current type is not collaboration enabled; however, the target must be collaboration enabled. See [Enabling Object Type Collaboration in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/collaboration) for more information about how collaboration works. ## Creating a Link Between Object Types Consider two API schemas, one with the object type `Order` and the other with the object type `Customer`:
Order SchemaCustomer Schema
ordersByOrderId (orderId:String!):Order
--------------------
--------------------
Order
--------------------
orderId: String!
Items: Item[]
customerId: String!
customersByCustomerId (customerId:String!): Customer
--------------------
--------------------
Customer
--------------------
customerId: String!
name: String!
Your unified schema currently looks like this: ```none ordersByOrderId (orderId:String!):Order customersByCustomerId (customerId:String!): Customer -------------------- -------------------- Order -------------------- orderId: String! Items: Item[] customerId: String! -------------------- -------------------- Customer -------------------- customerId: String! name: String! ``` In this current configuration, to query the order and the customer datasets at the same time, you must query both types separately: ```none ordersByOrderId (orderId: “123”) { orderId customerId } customersByCustomerId (customerId: “CC83”) { customerId name } ``` Additionally, to query the customer data for the order, you must know the customer ID associated with it. However, note that the `Order` object type has a field that returns `customerId`. You can _link_ your `Order` object type to the `Customer` object type using `customerId: String!` as a _foreign key_, pointing to `Customer` as your target type. Doing so causes your selected foreign key to map to the primary key `customerId:String!` on the `Customer` type. As a result of this link: - A new field called `Customer` is created in the `Order` object type that now returns the linked `Customer` object type. - The new object type generated in your API schema acts as a reference to the type in the `Customer` API schema, ensuring that any changes made to the `Customer` API schema do not affect your `Order` API schema: ```none ordersByOrderId (orderId:String!):Order -------------------- -------------------- Order -------------------- orderId: String! Items: Item[] customer: Customer -------------------- -------------------- Customer -------------------- -------------------- customerId: String! ``` In the updated unified schema, you can see that the `Order` type is linked to `Customer` type: ```none ordersByOrderId (orderId:String!):Order -------------------- -------------------- Order -------------------- orderId: String! Items: Item[] customer: Customer -------------------- -------------------- Customer -------------------- -------------------- customerId: String name: String ``` After linking, consumers of your unified schema can query the `Order` dataset along with its related `Customer` dataset without having to know the associated `customerId`: ```none ordersByOrderId (orderId: “123”) { orderId customer { name } } ``` ## Creating a Link Between Object Types That Use Composite Keys The default query method for a type can also use _composite keys_. Consider a target type `Customer` that uses composite keys for its default query method: `customerId` and `customerStatus`: ```none customerDetail (id: string!, status: string!): Customer -------------------- -------------------- Customer -------------------- customerDetail: string!, string! customerId: String! customerStatus: String! ``` Assuming the same `Order` schema from above: ```none ordersByOrderId (orderId:String!):Order -------------------- -------------------- Order -------------------- orderId: String! Items: Item[] customerId: String! ``` If you linked the `Customer` type as a target for the `Order` type, the unified schema reflects the link as follows: ```none ordersByOrderId (orderId:String!):Order -------------------- -------------------- Order -------------------- orderId: String! Items: Item[] customerId: Customer customerStatus: Customer -------------------- -------------------- Customer -------------------- -------------------- customerDetail: String!, String! customerId: String! customerStatus: String! ``` ## Additional Resources - [Create and Edit Links Between Object Types](https://docs.mulesoft.com/datagraph/manage-links) --- product: DataGraph --- # How Object Type Merges Work in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can merge an object type from your API schema with either another object type in your unified schema or another object type in the same API schema. Merging types enables you to combine similar types into a single type and extend their fields and datasets for a more enriched query result. You can only merge object types with other object types. You can have an _extension merge_, in which the merged types join data, or you can have a _composition merge_, in which the merged types simplify the unified schema but are joined without primary keys. In Anypoint DataGraph, the type you configure to merge is your _current type_ and the type you merge with is your _target type_. ## Merge Two Collaboration Enabled Types You can merge your current type with a target type that has collaboration enabled. If both types provide a primary key, you must ensure that both primary keys represent the same objects and identify the same record of that object. In this type of merge, known as an extension merge, both object types return the same dataset. For example, assume you have a Customer API Schema that returns a `Customer` type with default query method `customersById(id)` and primary key `id`: ```none customersById(id): Customer -------------------- -------------------- Customer -------------------- id: string! email: firstName: lastName: telephone: ``` You also have an API schema called `UserAccount` with a type `User`: ```none usersById(id): User -------------------- -------------------- User -------------------- id: email: address: Address accountId: type: organization: -------------------- -------------------- Address -------------------- addressLine1: addressLine2: city: postalCode: state: country: ``` Assume that both Customer and User types point to the same object type and return the same information for that same object. To have the same primary key value, both types must identify the same customer object. Moreover, any common fields between the types must also return the same values. For example, for `id = 1` in `Customer` type and `id = 1` in `User` type, the values of the email fields must be exactly the same. You might choose to merge the two types so that their combined data about the same customer can be queried in a single request. Additionally, because both types also have a default query method that retrieves the same object, you can also merge the types so that in the unified schema, there is only one joined query method and type: - Customer type - Default query method: `customersById(id): Customer` - Primary key: `id` - UserAccount type: - Default query method: `usersById(id): User` - Primary key: `id` The result is a single, merged, enriched type in the unified schema. ### How Types Are Ordered When Merged Whichever type is added first to the unified schema has the advantage of defining the name for the merged type and the corresponding default query method. In this example, because the Customer API type was added first, the resulting type in the unified schema is called `Customer`, containing all the fields from both Customer and UserAccount types. The resulting query method is called `customersById`, returning the merged `Customer` type: ```none customersById(id): Customer -------------------- -------------------- Customer -------------------- id: string! email: firstName: lastName: telephone: address: Address accountId: type: organization: -------------------- -------------------- Address -------------------- addressLine1: addressLine2: city: postalCode: state: country: ``` ## Merge Two Types When Only One Is Collaboration Enabled You can also merge two types when only one of the types has collaboration enabled. In this case, the merge causes your current type (the type you are configuring to merge) to act as a _reference_ to the target type (the type you are merging with). Note that for the merge to happen, the target type must have collaboration enabled, and both types must define one primary key or use [composite keys](#merge-types-composite-keys). After the merge is complete, the reference is declared and you can retrieve the fields only from your target type. If your current type has any other fields besides its primary keys, those fields become hidden and cannot be queried. For example, assume an `Order` API schema that returns a `Product` type: ```none ordersById(id: string!) : Order Order ---------- id: string! amount: float! date: string! product: Product ----------- ----------- Product ----------- id: string! name: string ------------ ``` And a `Product API Schema` that also returns a `Product` type: ```none productsById(id: string!) : Product Product ------------ id: string! name: string brand: string description: string unitPrice: float! quantityRemaining: int! ----------- ``` You can merge the Product type in the Order API schema to the Product type in the Product API schema. In this case, the Product type in the Order API schema becomes a reference to the Product type in the Product API. After merging, the unified schema looks like this: ```none ordersById(id: string!) : Order productsById(id: string!) : Product Order ---------- id: string! amount: float! date: string! product: Product ----------- ----------- Product ----------- id: string! name: string brand: string description: string unitPrice: float! quantityRemaining: int! ----------- ``` Note that now the `Order` type returns more data about the related product without you having to write a separate query. In this example, the primary key for both types is `id`, and for both APIs, `id` returns the same product object record. ## Merge Types That Use Composite Keys The types you merge can also have query methods that use _composite keys_. For example, assume the same `Order` API schema that returns a `Product` type: ```none ordersById(id: string!) : Order Order ---------- id: string! amount: float! date: string! product: Product ----------- ----------- Product ----------- id: string! name: string sku: string ------------ ``` Consider also a `SalesOrder` API that also returns a `Product` type but uses composite keys `id` and `sku`: ```none SalesOrder(id: string!, sku: string!) : SalesOrder Product ------------ id: string! sku: string! name: string brand: string description: string unitPrice: float! quantityRemaining: int! ----------- ``` After merging, the unified schema looks like this: ```none ordersById(id: string!, sku: string!) : Order SalesOrderByID(id: string!, sku: string!) : SalesOrder Order ---------- id: string! amount: float! date: string! product: Product ----------- ----------- Product ----------- id: string! sku: string! name: string brand: string description: string unitPrice: float! quantityRemaining: int! ----------- ``` ## Merge Two Types That Do Not Have Primary Keys Configured A composition merge occurs when you merge two types and neither has a primary key defined. This merging strategy does not require you to provide a default query method or a primary key. Because there is no primary key in either type, merging them does not join the datasets returned by the types but rather joins both types as a single one. In this merge, you do not reference the same object: you combine the fields. After merging the current and target types, all fields in the current type become nullable in the unified schema. The result of this merge does not affect the query results for the types, but it allows for a cleaner unified schema in case you have duplicate types that don’t return the same dataset. For example, assume you have a `Europe Sales API Schema` that returns an `Amount` type: Europe Sales API Schema ```none Amount ---------- currency: String price: float ``` You also have a `North America API Schema` that also returns an `Amount` type: North America API Schema ```none Amount ---------- currency: String price: float ``` You can merge them so that in the unified schema there is only one `Amount` type that returns data from the Europe Sales API or the North America Sales API, depending on the query. Although both types are similar, their datasets are not joined. ## Merge Input Types Input types are POST, PUT, and DELETE objects you use to modify information in your unified schema when you run mutations. You can merge two input types only when all their fields match. Both types must have the same number of fields and cannot contain subsets of fields. For example, assume you have an `OrderInput` API and a `PurchaseInput` API that contain the following identical fields: OrderInput ---------- orderId: String! customerEmail: String! customerId: String! OrderDate: String! product: Product Status: OrderStatus totalAmount: float You can merge the `OrderInput` API into the `PurchaseInput` API in the unified schema to consolidate these types. You do not need to, nor can you, enable collaboration to merge input types. ## Local Merges Between Objects in the Same API Schema A local merge occurs when you merge an object type with another object type in the same API schema. You can then merge the resulting type with another local object type or with a type in the unified schema. After a local merge, you can view and edit only the type that is the outcome of the merge. Additionally, you cannot enable or disable collaboration on the type or change its default query method or primary key. You can rename object types and fields, hide object types and fields, and merge and link with another object type. ### Field Visibility in Local Merges If you locally merge two object types that contain common fields but those fields have different visibilities, the fields in the locally merged type behave as follows:
ScenarioTypeA FieldTypeB FieldMergedType (Local)

1

Hidden

Hidden

Hidden

2

Hidden

Visible

Visible

3

Visible

Hidden

Visible

4

Visible

Visible

Visible

## See Also - [Create and Edit Object Type Merges](https://docs.mulesoft.com/datagraph/manage-merges) --- product: DataGraph --- # Promoting API Schemas > For the full documentation index, see: https://docs.mulesoft.com/llms.txt As you develop and configure an API schema, you can promote it to the next environment toward production and add it to that environment’s unified schema. Note that you’re promoting the schema configurations only, not the actual underlying source REST APIs. Promotion enables you to configure an API schema in one environment without repeating that configuration in subsequent environments. Use promotion to move your schema configurations from development to staging and from staging to production. The steps you take to promote an API through the production cycle vary depending on your needs. For example, imagine that you add and configure an Orders API in your development environment that you now want to promote to staging. The possible promotion scenarios are as follows:
Development Orders API VersionStaging Orders API VersionPromotion ActionPromotion Outcome Version

v3.1.0

None

Anypoint DataGraph promotes the API schema and any of its configuration.

You configure the URL and authentication method.

v3.1.0

v3.1.1

v3.1.0

Anypoint DataGraph automatically updates the asset version of the existing API schema.

You configure the URL and authentication method.

v3.1.1

v3.1.0

v3.1.0

Anypoint DataGraph updates any customizations to the asset version.

v3.1.0

v4.0.0

v3.1.0

Anypoint DataGraph adds both API versions to the target environment, where they coexist.

You configure the URL and authentication method for v4.0.0.

v3.1.0, v4.0.0

## Promote an API to Another Environment You can promote API schemas to any environment to which you are permitted access. Although your APIs must be published in Exchange, they do not need to be Mule applications or be running on Mule runtime engine or in CloudHub to be added to the unified schema. The schema you promote must not be in conflict with the unified schema in the target environment. If conflicts exist, you must instead manually add the API and resolve those conflicts as you would when adding an API. You must have [the Contribute or Admin permission](https://docs.mulesoft.com/datagraph/permissions). > [!IMPORTANT] Supported authentication methods to access your API from Anypoint DataGraph are > listed in the following procedure. Any other authentication methods, such as short-lived token > methods, are not supported. See > [Supported Authentication Methods](https://docs.mulesoft.com/datagraph/security#supported-authentication-methods) for more > information. To promote an API: 1. Click **List of APIs added** and select the API that you want to promote. 2. Click **Promote API schema**. 3. From the **Target environment** list, select the target environment for promotion. 4. Click **Next: Configure URL**. 5. Depending on your promotion scenario, optionally choose one of the following configuration options: - If your API is managed by API Manager or if you have added the API’s instances in Exchange, select **Get an existing URL from Anypoint Platform**. - If you prefer to provide your own implementation URL, select **Add a new URL** or click **Use the URL in API specification**. 6. Click **Next: Provide Authentication**. 7. On the **Provide authentication** page, select the type of authentication on the GET endpoints for the API that you want to add, allowing Anypoint DataGraph to make requests to your API when queried: - **No Auth**: Use if your API is public. - **Basic Auth**: Use if you authenticate to your API using a username and password. - **Pass-through**: Use if you authenticate to your API by passing authorization headers. - **Client ID enforcement via headers**: Use if you authenticate to your API passing `client_id` and `client_secret` headers. - **Client ID enforcement via query parameters**: Use if you authenticate to your API passing `client_id` and `client_secret` query params. - **OAuth 2.0 Client Credentials**: Use if you authenticate to your API by passing OAuth 2.0 `client_id`, `client_secret`, and authorization server values. - **Custom**: Use if you authenticate to your API using custom header parameters and values. 8. Optionally, add a keystore to configure mutual authentication (mTLS) between the API and DataGraph. > [!NOTE] If you’re promoting an API that already exists on the target environment, DataGraph > checks if the API on the target environment has an existing keystore or truststore. If a > keystore or truststore exist on the target environment, you can keep either, remove either, or > remove either and add new ones. You cannot automatically send the keystore and truststore from > the source environment to the target environment. To use the keystore and truststore from the > source environment in the target environment, you must remove and re-add them during the > promotion process. Select **Configure Keystore** and provide the following: - A public certificate signed by your organization’s “root” certificate authority (CA) - The private key used to generate the certificate signing request (CSR) - The password for the encrypted private key 9. Optionally, add a truststore to allow your API to be reached by your unified schema. Select **Configure Truststore** and provide the certificate bundle that contains your root CA. 10. Click **Next: Add to unified schema**. ## Promote an Updated API After you’ve updated an API version, you can promote the updated version to another environment. When you choose a new version of an API to promote, DataGraph lists any edits you’ve made to the current version that it can’t automatically apply to the new version in the target environment. For any edits DataGraph can’t automatically apply, you’ll have the option to manually apply these edits before you complete the promotion. Before you promote an updated API schema, you must first [update the API version](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema#update-an-api-version): 1. Click **List of APIs added** and select the appropriate API. 2. Click **API details**. 3. Click **Promote API schema**. 4. From the **Target environment** list, select the target environment for promotion. 5. Click **Next**. 6. If DataGraph finds changes it cannot apply, review the list of **Changes Not Applied** and manually apply them: 1. Select a change and click **Next**. 2. Edit the API schema as necessary and click **Apply Changes and Promote**. After you apply the change, repeat Step 5 for any additional changes. 7. Click **Next** to complete the remainder of the promotion steps. ## Additional Resources - [Permissions for Anypoint DataGraph](https://docs.mulesoft.com/datagraph/permissions) - [Resolve Conflicts and Merge Inconsistencies](https://docs.mulesoft.com/datagraph/resolve-conflicts) - [troubleshoot-schemas-queries.adoc#potential-errors-when-generating-an-api-schema](https://docs.mulesoft.com/datagraph/troubleshoot-schemas-queries#potential-errors-when-generating-an-api-schema) --- product: DataGraph --- # Removing APIs from the Unified Schema > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can remove APIs from the unified schema as needed. For example, remove an API to add a new version, or remove an API if the underlying REST API no longer exists. However, be aware that when you remove an API from the unified schema, you break: - Any merges and links with the types in the API schema that you remove - Any existing queries that query the types and fields of the API schema that you remove To remove an API: 1. Click **List of APIs added** and select the API that you want to remove. 2. Click **Remove API**, and then click **Apply Changes**. ## Additional Resources - [DataGraph Status Overview](https://docs.mulesoft.com/datagraph/status-updates) - [Edit Your API Schema to Add It to the Unified Schema](https://docs.mulesoft.com/datagraph/edit-schema) --- product: DataGraph --- # Resolving Conflicts and Merge Inconsistencies > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You must resolve any merge conflicts or merge inconsistencies when adding object types to the unified schema. ## Resolve Conflicts Between Object Types When adding types to your unified schema you must make sure that none of the types that you are adding create a conflict with the existing types in your unified schema. When you add an API schema that has a type name that already exists within your unified schema, Anypoint DataGraph raises an error. You must resolve this error before continuing. If you don’t care about adding this particular type to the unified schema, you can choose to hide the field. If you want to add this conflicting type to the unified schema you must either: - Hide the type or query method See [Schema Element Visibility in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/manage-elements-visibility) for more information. - Rename your type to avoid conflicting names See [Editing Names of Schema Elements](https://docs.mulesoft.com/datagraph/edit-elements-names) for more information. - Merge your new type with the existing type of the same name See [How Object Type Merges Work in Anypoint DataGraph](https://docs.mulesoft.com/datagraph/merge-types) for more information. ## Resolve Merge Inconsistencies Resolve inconsistencies and other issues across object types and fields before merging. The following is a list provides example issues: - You can’t change the visibility of a common field after a merge if visibility is not the same in both types. If you merge two object types that contain a common field, and the common field is hidden on ObjectType1 but is visible on ObjectType2, you can’t change the visibility of the common field after a merge. Instead, you’ll need to split the object types, change the field settings and merge them again. - You can’t merge object types if the target type is not current. If you try to merge an object type with an object type in the unified schema while another user is updating the unified schema, the merge will fail and DataGraph won’t apply your changes. You’ll need to cancel the merge, update your local version of the unified schema, and redo the merge. - You can’t change the visibility of the only remaining field for a type after a merge. If you merge two object types, each with two unique visible fields—ObjectType1 contains FieldA and FieldB; ObjectType2 contains FieldC and FieldD—and you hide FieldA and then merge the object types, you can’t later change the visibility on FieldB without breaking the merge since FieldB is the only remaining visible field from ObjectType1. Instead, you’ll need to split or undo the merge, change the field settings, and merge them again. - Unhiding an object type with a duplicate name will create a conflict. If there is a hidden object type in your local API schema that has the same name as another object type in the unified schema or in the same schema, unhiding that object type will raise a conflict. You’ll have to rename the object type or merge it with the object type with the same name after unhiding it. - Hiding a type that you’ve merged will undo the merge. If you merge object types in the unified schema, and then hide either of the contributing types, the object types will no longer be merged. You will have to make the hidden object type visible and merge them again. ## Additional Resources - [Potential Errors When Generating an API Schema](https://docs.mulesoft.com/datagraph/troubleshoot-schemas-queries) - [Edit Your API Schema for Addition to the Unified Schema](https://docs.mulesoft.com/datagraph/edit-schema) --- product: DataGraph --- # Retrieving the Unified Schema and Diagnostic Data > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can download a copy of the unified schema from the query editor or by using a third-party API client. You can download diagnostic data from the **List of APIs added** page in DataGraph. The schema is downloaded as a `.graphql` file. Diagnostic data is downloaded as JSON files. ## Download the Unified Schema from the Query Editor To download the schema from the query editor, you need the [consumer, contributor, or admin permission](https://docs.mulesoft.com/datagraph/permissions). 1. Navigate to the query editor. 2. From the actions menu (**…​**), select **Download Schema**. ## Retrieve the Unified Schema Using an API Client To retrieve a copy of the unified schema, you need the following: - The graph endpoint of your unified schema, which you can obtain from the homepage of Anypoint DataGraph. - The `client_id` and `client_secret` values you use to query the unified schema, which you can obtain from the [Client Applications page](https://docs.mulesoft.com/api-manager/latest/datagraph-viewing-application-contracts) in API Manager. In the API client of your choice, run a GET request with the following information: - The graph endpoint of the unified schema appended with `/schema` - Your `client_id` and `client_secret` headers For example, the complete command looks like: ```copy curl https:///schema \ -H 'client_id: ' \ -H 'client_secret: ' ``` ## Download Diagnostic Data When you download diagnostic data, DataGraph downloads diagnostic data for API sources you’ve added to that environment. To download Source APIs, you need the [contributor or admin permission](https://docs.mulesoft.com/datagraph/permissions). 1. Navigate to the **List of APIs added** page. 2. In the right-hand corner of the API list, click **…​** > **Download Diagnostic Data**. --- product: DataGraph --- # Running Queries and Mutations > For the full documentation index, see: https://docs.mulesoft.com/llms.txt The unified schema resolves into a single GraphQL endpoint. To run queries or mutations against the unified schema, you first request access (if applicable) and then write and run a GraphQL query in the query editor. ## Before You Begin - You must have [the Consume, Contribute, or Admin permission](https://docs.mulesoft.com/datagraph/permissions). - Review [Anypoint DataGraph API Support](https://docs.mulesoft.com/datagraph/#anypoint-datagraph-api-support) ## Request Access to Run a Query Before you can run a query or mutation, you must request access. If you’re using an external client provider, refer to [Request Access to Environments Using an External Client Provider](#request-access-to-environments-using-an-external-client-provider) 1. Click **Run Operation**. 2. In the **Request access to run queries** dialog, select how you want to get access to run your queries. If you want to use an existing client application or client ID and secret pair, you can find them in Exchange. Open Exchange in a new tab, navigate to **My applications** and select an application from the list to find relevant information. Choose one of the following options: - **Use one of my existing applications**: Choose an existing client application from the list, and click Request Access. - **Create a new application and use it immediately**: Click **Next**, provide an application name and an optional description and application URL, and click **Create and Request Access**. - **I already have credentials…​**: Click **Next**, provide an existing client ID and secret pair, and then click **Authenticate & Request Access**. 3. To change your access method from the query editor, from the actions menu (**…​**), select **Switch Current Credentials**. ## Run a Query Use the query editor to write, run, and troubleshoot queries. 1. If any of the APIs in the unified schema require pass-through authentication, click **Add HTTP Headers**, and: 1. Select a header name. 2. Enter a header value. 3. To specify additional header name and value pairs for other APIs, click **+Add Header** x 4. Click **Save**. 5. To edit the HTTP headers, click **Edit HTTP Headers**. 2. In the query editor, start typing your query using the in-line autocomplete function or type **Option/Alt + Shift + Space** to open the autocomplete menu. ![Using inline autocompletion to write a query](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-autocompletion.png) 3. Optionally, in the **Query Variables** pane, add any query variables you want to use. ![Inserting a query variable in the query editor](/mulesoft/current/en-us/datagraph/_images/datagraph-query-variable.png) 4. Click **Run**. ![Query editor displays query results](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-result.png) 5. To see results with query tracing, from the actions menu (**…​**), select **Trace Query**, and then click **Run**. ![Query trace view open with query results](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-traces.png) Query trace results for DataGraph provide the following information: - Time taken by DataGraph to parse and validate the query - Total response time for the entire query - Duration of requests to each source API in the query 6. To see response logs associated with the query, from the actions menu (**…​**), select **View Response Logs**. ![Query response logs page](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-response-logs.png) Log levels for DataGraph include DEBUG, INFO, WARN, and ERROR. 7. Click **View History** to access this same query (or others) later. 8. To use this query in your application, click **Copy endpoint** to copy the query and the automatically generated GraphQL endpoint. You can also copy the query as a curl snippet. ## Run a Mutation Use the query editor to write and then run mutations. If needed, you can also troubleshoot mutations in the query editor 1. If any of the APIs in the unified schema require pass-through authentication, click **Add HTTP Headers** and: 1. Select a header name. 2. Enter a header value. 3. To specify additional header name and value pairs for other APIs, click **+Add Header**. 4. Click **Save**. 5. To edit the HTTP headers, click **Edit HTTP Headers**. 2. In the query editor, start typing your mutation using the in-line autocomplete function, or type **Option/Alt + Shift + Space** to open the autocomplete menu. ![Using inline autocompletion to write a mutation](/mulesoft/current/en-us/datagraph/_images/datagraph-mutation-autocomplete.png) 3. Optionally, in the **Query Variables** pane, add any variables you want to use. 4. Click **Run**. ![Query editor displays mutation results](/mulesoft/current/en-us/datagraph/_images/datagraph-mutation-result.png) 5. To see results with query tracing, from the actions menu (**…​**), select **Trace Query** and then click **Run**. 6. To see response logs associated with the query, from the actions menu (**…​**), select **View Response Logs**. 7. Click **View History** to access this same mutation (or other) later. 8. To use this mutation in your application, click **Copy endpoint** to copy the query and the automatically generated GraphQL endpoint. You can also copy the query as a curl snippet. ## Query Editor Shortcuts The following table provides shortcuts you can use in the query editor:
FunctionShortcut

Prettify query

Shift+Ctrl+p

Run operation

Ctrl+Enter

Autocomplete

Ctrl+space

Comment-out line

Cmd+/

Jump to end or start of current scope

Cmd+m

Highlight current word

Cmd+d

Regex search

Cmd+f

Search and replace

Cmd+h

Bring next line up to current line

Cmd+j

Delete rest of line past cursor

Cmd+kk

Highlight current line

Cmd+l

Outdent current line

Cmd+[

Indent current line

Cmd+]

## Request Access to Environments Using an External Client Provider API Manager enables you to configure different client providers for each one of your environments. Depending on the environment where your data graph runs, your client applications might need to authenticate using either the default Anypoint Platform native client provider or any of the supported external client providers. See [About Client Management](https://docs.mulesoft.com/access-management/managing-api-clients) for more information. If you don’t configure any specific client provider for an environment, Anypoint Platform uses its default and native client provider. When your environment uses an external client provider, the **Request access** pop-up shows the required and optional fields defined in the external client provider implementation. For example, when querying the `/api-federation/xapi/organizations/{organizationID}/environments/{environmentID}/type/federation/api/clientProvider/` endpoint, returns the configured grant types for that environment: ```JSON { "id": "aaaaaaaa-1a1a-1a1a-1a1a-aaaa1111aaa1", "name": "OpenAM", "typeName": "openam", "grantTypes": [ { "name": "password", "label": "Resource Owner Grant", "depends": [], "exclude": [], "required": true (1) }, { "name": "implicit", "label": "Implicit Grant", "depends": [], "exclude": [], "required": true (1) }, { "name": "client_credentials", "label": "Client Credentials Grant", "depends": [], "exclude": [ "authorization_code" (2) ], "required": false }, { "name": "authorization_code", "label": "Authorization Code Grant", "depends": [], "exclude": [ "client_credentials" (2) ], "required": false } ] } ``` Those grant types properties are reflected in the UI when configuring access for a client: ![Requesting access using an external client provider](/mulesoft/current/en-us/datagraph/_images/confirm-credentials.png)
1Both Resource Owner Grant and Implicit Grant are marked as required in the UI.
2Both Client Credentials Grant and Authorization Code Grant are mutually exclusive in the UI.
## Additional Resources - [Writing GraphQL Queries and Mutations in DataGraph](https://docs.mulesoft.com/datagraph/write-queries-tutorial) - [Anypoint DataGraph Troubleshooting](https://docs.mulesoft.com/datagraph/troubleshoot-schemas-queries) - [Configure Multiple Client Providers for Client Management in API Manager](https://docs.mulesoft.com/api-manager/latest/configure-multiple-credential-providers) --- product: DataGraph --- # Scaling API Calls in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint DataGraph provides you the option to configure the number of API calls permitted for a unified schema. Increasing or decreasing API calls enables you to process higher workloads and optimize your consumption when needed. ## How API Call Scaling Works in DataGraph By default, DataGraph supports a maximum of 1 million annual API calls and 150 concurrent or ongoing calls per unified schema per environment. You can update the maximum number of annual and concurrent calls after you add the first API to the unified schema. However, your plan must allocate the correct number of vCores for your business group or organization before scaling. You can’t scale API calls in an environment beyond the free capacity remaining in the number of vCores allocated for that environment. Production and Sandbox environments each have their own scaling options per unified schema. The **API Call Scaling** page displays available scaling options: ![api call scaling](/mulesoft/current/en-us/datagraph/_images/api-call-scaling.png) Each option includes **Annual API Calls**, which are the total number of API requests you can make to the unified schema on a yearly basis. When you select an annual option, you also select: - **Concurrent Calls**: The number of active API requests the unified schema can process in parallel - **\# of Workers**: The number of dedicated Mule instances that can actively process requests to the unified schema The **Insufficient Capacity** label indicates that your business group hasn’t allocated enough capacity to select that option. Your business group administrator can increase capacity either by reducing usage in other environments or by purchasing additional capacity for your business group. ## Available Scaling Options The following table provides details about the available scaling options:
Annual API CallsConcurrent Calls# of Workers

100M

150

1

200M

300

2

300M

450

3

400M

600

4

500M

750

5

600M

900

6

700M

1050

7

800M

1200

8

## Configure API Call Scaling Use API call scaling to increase or decrease the number of API calls that can be made to the unified schema for the current environment. You can’t make any adjustments until you add at least one API to the unified schema. You must have the DataGraph [admin or operator permission](https://docs.mulesoft.com/datagraph/permissions). 1. From Anypoint Platform > Anypoint DataGraph, click **Settings**. 2. In the **API Call Scaling** tab, choose an available option. 3. Click **Save Changes**. ## Related Resources - [Add an API to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema) - [View Usage Metrics for DataGraph](https://docs.mulesoft.com/datagraph/usage-metrics) - [DataGraph API Support](https://docs.mulesoft.com/datagraph/#anypoint-datagraph-api-support) --- product: DataGraph --- # Schema Element Visibility in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can hide the fields, types or query methods that you don’t want to have visible in the unified schema. The fields, types, or query methods that you hide make them unavailable for querying. Managing the visibility of your schema elements keeps your unified schema manageable and clean. You can modify the visibility of your elements later. In Anypoint DataGraph, the elements that you choose to hide are _hidden_, and the elements that you choose to unhide are _visible_. By default, all nested types are hidden. If you wish to add a nested type to the unified schema, and query it, you must unhide it first. You cannot hide a method that you configured to be a default query method, or a field that you configured as a primary key. ## Manage Visibility of Schema Elements Hiding or unhiding elements in your API schema allows you to control the granularity of information that is available in the unified schema. In the API schema, choose the object, field, or method for which you want to manage visibility, and click the **Hidden/Visible** toggle. You must hide or unhide elements _before_ adding them to the unified schema. ![Setting order item summary visibility desired state to Visible](/mulesoft/current/en-us/datagraph/_images/visible-object-type.png) --- product: DataGraph --- # Setting Dedicated Load Balancer URLs for Anypoint Datagraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt If you’re unable to use Port 8082 on a CloudHub shared load balancer, you must set a URL for Anypoint DataGraph to use on a dedicated load balancer (DLB). To set the URL, add a DLB mapping rule to the Anypoint DataGraph configuration. ## Example Mapping Rules for a DLB URL Based on the way DLB mapping rules work, you must configure the **Input Path** (Input URI) and the **Output Path** (App URI) so that the final DLB URL is able to access the endpoint of the Anypoint DataGraph application, which is `/graphql`. For example, consider the following mapping rules for `examplelb.lb.anypointdns.net` depending on the value of the **Input Path** and a Datagraph app name of `datagraph-xz082edx-1585-901xe374-d0x0`:
IndexInput URI (Input Path)App nameApp URI (Output Path)Protocol

0

/graphql

datagraph-xz082edx-1585-901xe374-d0x0

/graphql

HTTPS

1

/datagraph/

datagraph-xz082edx-1585-901xe374-d0x0

/graphql

HTTPS

2

/datagraph/

datagraph-xz082edx-1585-901xe374-d0x0

/

HTTPS

3

/{app}/

{app}

/

HTTPS

For each index, the appropriate DLB URL is: - Index 0: `examplelb.lb.anypointdns.net/graphql` - Index 1: `examplelb.lb.anypointdns.net/datagraph/` - Index 2: `examplelb.lb.anypointdns.net/datagraph/graphql` - Index 3: `examplelb.lb.anypointdns.net/datagraph-xz082edx-1585-901xe374-d0x0/graphql` ## Prerequisites - You must have the [Admin or Operator permission](https://docs.mulesoft.com/datagraph/permissions) for the environment in which you want to specify a DLB URL. - You must be able to [authenticate to](https://docs.mulesoft.com/anypoint-cli/latest/#authentication) and run commands from the Anypoint CLI. - You must be familiar with [creating DLB mapping rules](https://docs.mulesoft.com/cloudhub/lb-mapping-rules). - You must [create and configure a DLB](https://docs.mulesoft.com/cloudhub/cloudhub-dedicated-load-balancer#create-and-configure-a-dedicated-load-balancer). To complete this task, you: 1. Use the Anypoint CLI to gather details about your DLB and Anypoint DataGraph. 2. Use Anypoint Runtime Manager to create a mapping rule for the DLB. 3. Use the Anypoint CLI to add the DLB configuration to Anypoint DataGraph. ## Gather Details about the DLB and Anypoint DataGraph Gather the name of your DLB and the app name for Anypoint DataGraph. 1. Connect to the Anypoint CLI using your Anypoint Platform username and password. 2. If you did not previously set the environment, do so with the following command: - Using Anypoint CLI v3.x: `use environment ` - Using Anypoint CLI v4.x: `conf environment ` 3. Get the name of the DLB: - Using Anypoint CLI v3.x: `cloudhub load-balancer describe ` - Using Anypoint CLI v4.x: `cloudhub:load-balancer:describe ` The expected output resembles: `Name | examplelb` 4. Get the CloudHub domain for the Anypoint DataGraph app name: - Using Anypoint CLI v3.x: `datagraph load-balancer-config describe` - Using Anypoint CLI v4.x: `datagraph:load-balancer-config:describe` The expected value resembles: `Domain | datagraph-xz082edx-1585-901xe374-d0x0` The DataGraph app name contains elements from your org ID and the environment ID. 5. Note the values for steps 3 and 4. ## Create a Mapping Rule for the DLB You set up the mapping rule in Runtime Manager. 1. From Anypoint Platform, select **Runtime Manager**. 2. From the navigation menu, select **Load Balancers**. 3. Click a load balancer name, and then click a certificate name. Ensure your load balancer has a valid, CA-signed certificate, or the browser won’t connect to Anypoint DataGraph. 4. In the **URL Mapping Rules** section, click **Add New Rule**. 5. Complete the fields with the following values: - **Input Path** (`inputUri`): The URI that the client requests: for example, `/{app}/` - **Target App** (`appName`): The domain for the Anypoint DataGraph application discovered in Step 4 of the gathering details task - **Output Path** (`appURI`): The URI string to pass to Anypoint DataGraph; for example `/` or `/graphql` - **Protocol** (`upstreamProtocol`): https Anypoint DataGraph supports only HTTPS. ## Add the DLB Configuration to Anypoint DataGraph After you add the mapping rule, you configure the DLB for use with Anypoint Datagraph. 1. Check the DLB URL for Anypoint DataGraph: - Using Anypoint CLI v3.x: ```copy datagraph load-balancer-config describe ``` - Using Anypoint CLI v4.x: ```copy datagraph:load-balancer-config:describe ``` By default, no value is returned for `dlbUrl` if you haven’t previously configured a DLB for that Anypoint DataGraph environment. 2. Add the new DLB URL: - Using Anypoint CLI v3.x: ```copy datagraph load-balancer-config add ``` - Using Anypoint CLI v4.x: ```copy datagraph:load-balancer-config:add ``` Replace `` with a valid URL that includes the DLB name and DataGraph app name (gathered in Steps 3 and 4 of the gathering details task) and the mapping rule **Input Path**, for example: - Using Anypoint CLI v3.x: ```copy datagraph load-balancer-config add examplelb.lb.anypointdns.net/datagraph/graphql ``` - Using Anypoint CLI v4.x: ```copy datagraph:load-balancer-config:add examplelb.lb.anypointdns.net/datagraph/graphql ``` Refer to [Example Mapping Rules for a DLB URL](#example-mapping-rules-for-a-dlb-url) if needed. 3. Validate that the value was updated: - Using Anypoint CLI v3.x: ```copy datagraph load-balancer-config describe ``` - Using Anypoint CLI v4.x: ```copy datagraph:load-balancer-config:describe ``` The CLI returns details that include the application name for the Anypoint DataGraph load balancer and the full domain name for the DLB. After you add this change, Anypoint DataGraph re-deploys, and you must wait for the status indicator to indicate that Anypoint DataGraph is up to date. ## Remove the DLB Configuration from Anypoint DataGraph You can remove the DLB configuration using the following command: - Using Anypoint CLI v3.x: ```copy datagraph load-balancer-config remove ``` - Using Anypoint CLI v4.x: ```copy datagraph:load-balancer-config:remove ``` When you remove the configuration, Anypoint DataGraph redeploys. ## Additional Resources - [Anypoint DataGraph Hosting Options and Networking](https://docs.mulesoft.com/datagraph/hosting-options) - [Add an API Schema to the Unified Schema](https://docs.mulesoft.com/datagraph/add-api-to-unified-schema) - [DataGraph CLI](https://docs.mulesoft.com/datagraph/datagraph-cli) --- product: DataGraph --- # Troubleshooting Queries With Response Logs > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint DataGraph provides response logs that contain useful query troubleshooting information. Response logs contain information about only Anypoint DataGraph queries. Anypoint DataGraph stores up to 100 MB or up to 30 days of log data, whichever limit is reached first. If your organization has the Anypoint Integration Advanced package or a Titanium subscription to Anypoint Platform, this feature provides a higher resource allocation. For more information on log limits, see [limits in Anypoint Monitoring](https://docs.mulesoft.com/monitoring/am-faq#titanium-subscription-limits.adoc). ## Log Levels for Anypoint DataGraph Response Logs Log levels for Anypoint DataGraph include DEBUG, INFO, WARN, and ERROR. Log levels are incremental, and each level contains the following information:
Log levelDescriptionLevels included

DEBUG

Logs information for request headers and request queries

All levels

INFO

Logs information for request queries, response times, and the underlying API URLs requested per field in queries

INFO, WARN, and ERROR

WARN

Lists warning messages

INFO, WARN

ERROR

Lists error messages on invalid queries, timeouts, authentication failures, and payload errors

ERROR

By default, the log level for each environment is set to INFO. You can change this setting at any time. Changes to the log level persist for _all future queries to that Anypoint DataGraph instance_, regardless of the user. ## View Response Logs for an Operation You must have [the Operate or Admin permission](https://docs.mulesoft.com/datagraph/permissions) to view and search response logs. If you are a Titanium subscriber, you can also view response logs in [Anypoint Monitoring](https://docs.mulesoft.com/monitoring/logs). To view response logs in Anypoint DataGraph: 1. Write and run an operation. 2. From the actions menu (**…​**), select **View Response Logs**. Response logs for that query are displayed: ![Query response logs page](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-response-logs.png) ## Search Response Logs Search for logs that contain specified values or search for logs by date and priority. The **Date & Time** filter enables you to search logs by specifying a date range using the following values: - Last hour - Last 24 hours - Last week - Last month You can also filter searches by priority level: - All priorities - INFO - DEBUG - WARN - ERROR To search existing logs: 1. Enter a value in the search box, or click Advanced to search for logs for a specified time, day, date range, and message priority. ![Search fields for query response logs](/mulesoft/current/en-us/datagraph/_images/search-logs.png) 2. Click **Apply**. ## Additional Resources - [Troubleshoot Query Performance with Query Tracing](https://docs.mulesoft.com/datagraph/troubleshoot-query-traces) - [Run Queries and Mutations](https://docs.mulesoft.com/datagraph/query-unified-schema) ## See Also - [Known Issues](https://help.salesforce.com/s/issues) --- product: DataGraph --- # Troubleshooting Query Performance with Query Tracing > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Query tracing in Anypoint DataGraph helps you analyze query performance by tracing every call made to the source APIs of the unified schema for a given query. Trace results provide the following information: ![Detailed view of a query trace](/mulesoft/current/en-us/datagraph/_images/query-trace-details.png)
1Time taken by Anypoint DataGraph to parse and validate the query
2Total response time for the entire query
3Errors identified during query execution
4Lack of trace information, denoted by a fading line
5Duration of requests to each source API in the query
## Prerequisites You must have [the Contribute or Admin permission](https://docs.mulesoft.com/datagraph/permissions) to use query tracing. ## Run a Query Trace Query trace results are provided as soon as you run an operation. 1. From the actions menu (**…​**), select **Trace Query**. 2. Write your query. 3. Click **Run**. The trace query panel opens and displays results: ![Query traces enabled on a query](/mulesoft/current/en-us/datagraph/_images/datagraph-qsg-query-traces.png) You can collapse and expand the query trace panel as needed. ## Additional Resources - [Troubleshoot Queries with Response Logs](https://docs.mulesoft.com/datagraph/troubleshoot-query-logs) - [Run Queries and Mutations](https://docs.mulesoft.com/datagraph/query-unified-schema) ## See Also - [Known Issues](https://help.salesforce.com/s/issues) --- product: DataGraph --- # Understanding the Elements in an API Schema > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint DataGraph organizes all data that you choose to make available to your clients in a unified schema. The unified schema is a single, always-current collection of all of the schemas of all of the APIs that you add to it. When you add a new API to your unified schema, Anypoint DataGraph generates an API schema from the API’s RAML or OAS specification. Because each API schema is created when its API is added, your unified schema is always up to date. And because all API schemas are stored individually in your organization, you can edit them individually without affecting the integrity of other schemas. The API schema that Anypoint DataGraph generates contains a collection of the GET resources and entities, and the relationships between them, that you’ve defined in your API specification. Whenever you add a new API schema to the unified schema, you can configure the types and fields that the unified schema will include. Before learning about the different configurations that you can apply to a type, read the following topic to understand the different types that can be present in your API schema depending on your API specification. ## Object Types and Fields The most common type in a schema, object types represent entities in your API specification that are returned as part of a GET response. Object types are descriptively named and contain fields that indicate the object properties. For example, in a RAML specification, each type element of the specification becomes either an object, enum, or union type. And the properties of each type element are the fields of those object types in the API schema:
RAML API SpecificationAPI Schema
#%RAML 1.0
title: Order API

types: Order: type: object properties: orderId: date: status:

Product: type: object properties: productId: name: brand:

/orders/{id}: get: displayName: Get Order by ID
ordersById(id):
Order
--------------------

---

Order
--------------------

orderId: ID! date: String status: String
--------------------

---

Product
--------------------

productId: ID! name: String brand: String
Both `Order` and `Product` are different object types, each with different fields, that can be represented as follows: ```none type Order { orderId: ID! date: String! status: String! } ``` ```none type Product { productId: ID! name:String! brand: String! } ``` ### Field Data Types Each field represents a type’s dataset that is returned in a query response. By default, there are five scalar types: - `Int`: A signed 32‐bit integer. - `Float`: A signed double-precision floating-point value. - `String`: A UTF‐8 character sequence. - `Boolean`: `true` or `false`. - `ID`: The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a query method. The ID type is serialized in the same way as a String; however, defining it as an ID signifies that it is not intended to be human‐readable. ### Non-nullable Fields Fields with values represented with a `!` sign are non-nullables, meaning that the field cannot respond with a null value. For example, in the `Product` type, ID cannot be null: ```none type Product { productId: ID! name:String brand: String } ``` And in the `Order` type, none of the values can be null: ```none type Order { orderId: ID! name: String! price: String! brand: Int! } ``` ## Query Types and Methods A query type is the entry point to your API schema when you make a request. A query type contains the query methods that represent the GET endpoint you’ve defined in your API specification. For example, in a RAML specification that defines a GET endpoint at `/orders/{id}`, the query method in the schema is `ordersById(id)`:
RAML API SpecificationAPI Schema
#%RAML 1.0
title: Order API

/orders/{id}: get: displayName: Get Order by
ID
ordersById(id):
Order
## Level-1 and Nested Types The types in your schema belong to categories that depend on the relation between your type and the query methods: - Level-1 type These types have a query method associated with them and therefore can be accessed directly. For example, in the previous API specification, `Order` is a Level-1 object type because there is a GET for the `order/{id}` endpoint associated with it. You can access this object type using the query method directly: ```none ordersById (orderId: “123”) { orderId date } ``` - Nested types These types have no query methods associated with them and therefore you can access them only through the query methods of Level-1 types. For example, in the previous API specification, `Product` is an object type with no query methods associated with it. To query the fields of the `Product` type, you must query the method associated with its Level-1 type `Order`: ```none ordersById(id: "123") { orderId product { name price } } ``` Following this structure, query methods can be considered a level 0 type. ## Enum Types Enum types are types that can only return a specific set of values. Enum types can be declared in the API specification to ensure that a field always returns a finite set of values. For example, assume a RAML specification that defines an `OrderStatus` type that must return one of the object types `Processing`, `Completed`, or `Canceled`:
RAML API SpecificationAPI Schema
#%RAML 1.0
title: Order API

types: OrderStatus: type: string description: Current status of the order enum: [Processing,
Completed, Canceled]
enum
OrderStatus { Processing Completed Canceled
}
## Union Types Union types describe instances of data using other object types. Union types consists of one or more specific object types. For example, a RAML specification can define the type `Product` using other types, such as `Notebook` and `Phone`:
RAML API SpecificationAPI Schema
#%RAML 1.0
title: Order API

types:

Product: type: Phone | Notebook

Notebook: type: object properties: manufacturer: type: string numberOfUSBPorts: type: number kind:
string

Phone: type: object properties: manufacturer: type: string numberOfSIMCards: type: number kind:
string
Product
--------------------

Notebook Phone
--------------------

---

Notebook
--------------------

manufacturer: String numberOfUSBPorts: int
--------------------

---

Phone
--------------------

manufacturer: String numberOfSIMCards: int
## Mutations and Input Types _Mutations_ are operations you use to add, update, and delete data objects. In GraphQL, mutation operations represent the POST, PATCH, PUT, DELETE, and HTTP methods that you’ve defined in your REST API specification. For example, this RAML specification defines a POST endpoint at `/createOrder/{OrderInput}`, and the mutation method in the schema is `createOrder(input:OrderInput)`:
RAML API SpecificationAPI Schema
#%RAML 1.0
title: Order API

/createOrder/{OrderInput}: post: displayName: Create Order by
OrderInput
createOrder(input:OrderInput):
Order
Input types represent the attributes of objects created by mutation operations. Input types are POST, PUT, and DELETE request objects you use to modify information in your unified schema when you run mutations. For example, you can post to the `OrderInput` input type using the `/createOrder/{OrderInput}:` mutation: createOrder (input: “123”) { orderId customerEmail cutomerID orderDate product status totalAmount } ## Additional Resources - [Writing GraphQL Queries and Mutations in DataGraph](https://docs.mulesoft.com/datagraph/write-queries-tutorial) - [Anypoint DataGraph Quick Start Guide](https://docs.mulesoft.com/datagraph/datagraph-qsg) --- product: DataGraph --- # Using Anypoint Platform DataGraph CLI and API Extensions > For the full documentation index, see: https://docs.mulesoft.com/llms.txt You can use the Anypoint CLI DataGraph commands to add and edit API sources in DataGraph. To do so, you must first add the appropriate DataGraph API extensions to the API source. ## Adding Extensions to Your Project You must add the extensions to your API-specification project as a dependency and then publish the project to Exchange. After you publish your API-specification project, you can add the API to DataGraph using the CLI. Use API Designer to add the extensions to your project. Follow the steps in [Add Dependencies to an API-Specification Project](https://docs.mulesoft.com/design-center/design-add-api-dependency#add-dependencies-to-an-api-specification-project), choosing **Fragments** as the dependency type. API Designer adds the required dependencies to `exchange.json` and validates the syntax of any annotations you added before publishing your project to Exchange. ## Maintaining RAML Compatibility To maintain compatibility in RAML specifications with tools that do not support API extensions, these extensions include a “RAML companion” that provides a simple version of RAML annotations definition. To use DataGraph API extensions in RAML, add the following code to the main file of the API-project specification: uses: dg: exchange\_modules////datagraph-api-extensions.raml You can change the prefix `dg` if needed, but it must match the prefix used in the extensions. The ``, ``, and `` reference the API extensions that are published in Exchange. ## Using the DataGraph CLI versus the DataGraph UI If you add an API source using the CLI, you cannot edit it or update its version directly in the UI. You must make these changes using the CLI. ## See Also - [Anypoint DataGraph API Extension Reference](https://docs.mulesoft.com/datagraph/api-extensions) - [Anypoint DataGraph CLI Reference](https://docs.mulesoft.com/datagraph/datagraph-cli) --- product: DataGraph --- # Using Automatic Persisted Queries and Content Delivery Networks with Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To improve performance and decrease potential bottlenecks in your network traffic, DataGraph supports automatic persisted queries. You can also use persisted queries in conjunction with content delivery networks (CDNs) to deliver cached results much faster than requiring a roundtrip to the DataGraph server. ## How Automatic Persisted Queries Work in DataGraph To create a persisted query, you send a POST request that contains: - The GraphQL query and any query variables. - The `persistedQuery` extensions parameter that includes a unique ID, ideally created with a hashing algorithm, such as SHA-256. Using a hash limits the chance of collisions and allows multiple clients to access the query using the same ID. After you’ve created the persisted query, you can subsequently send a GET request to DataGraph by passing the hash ID as a persistedQuery extensions parameter. ## Register an Automatic Persisted Query to DataGraph To post a persisted query, ensure that you have: - The DataGraph Consume permission - An authenticated connection to DataGraph using a valid client ID and secret - An ID for the persisted query To register a persisted query, create a POST request that contains the following: - The endpoint for the DataGraph instance - An extension that contains the `persistedQuery` parameter - An ID within the `persistedQuery` parameter - A GraphQL query and any variables The following example shows how to register a persisted query using curl: ```copy curl --location --request POST 'https:///graphql' \ --header 'Content-Type: application/json' \ --data-raw '{ "extensions": { "persistedQuery": { "version": 1, "sha256Hash": "bcd3868f0cb4f723cdb5bdbc433d6ab73156f0b9d0e9d5bd17e200cdab6fba4" } }, "query": "{\n customers(customersCount: 30) {\n customerId\n name\n }\n}", "variables": {} } ``` ## Request a Persisted Query from DataGraph To request a persisted query from DataGraph, ensure that you have: - The DataGraph Consume permission - An authenticated connection to DataGraph using a valid client ID and secret To request a persisted query, create a GET request that contains the following: - The endpoint for the DataGraph instance - An extension that contains the `persistedQuery` parameter - An ID within the `persistedQuery` parameter The following example shows how to request a persisted query using curl: ```copy curl --location --request GET 'https:///graphql?extensions=%7B%0A%20%20%22persistedQuery%22%3A%20%7B%0A%20%20%20%20%22version%22%3A%201%2C%0A%20%20%20%20%22sha256Hash%22%3A%20%22acf31818e50ac3e818ca4bdbc433d6ab73176f0b9d5f9d5ad17e200cdab6fba4%22%0A%20%20%7D%0A%7D' ``` ## Troubleshoot Query Not Found Errors If you send an ID in a request and a query is not found, DataGraph returns an error that the query is not persisted. { "errors": \[ { "message": "PersistedQueryNotFound", "locations": \[\], "extensions": { "persistedQueryId": "bcd3868f0cb4f723cdb5bdbc433d6ab73156f0b9d0e9d5bd17e200cdab6fba4", "classification": "PersistedQueryNotFound" } } \] } At this point, you can send a new POST request with a query and ID to register the query and then subsequently request the query. ## Using Automatic Persisted Queries with a CDN Content Delivery Networks (CDNs) enable you to cache full responses to GET operations to speed performance of your APIs. Because the cache functionality of many CDNs supports only GET requests, you can sync persisted queries in DataGraph to your CDN for fast retrieval. > [!NOTE] The ability to configure and work with a CDN is required. ### How CDNs Work with Automatic Persisted Queries in DataGraph The process to sync persisted queries from DataGraph with a CDN is as follows: 1. You register a persisted query to DataGraph. 2. You make a GET request to the CDN by passing the ID of the persisted query. 3. The CDN routes the request to DataGraph. 4. DataGraph returns the response with a header that includes cache-control directives that you’ve added to the API. 5. The response is stored in the CDN and sent back to you. 6. You can issue subsequent GET requests to the CDN and retrieve the response. ### Supported Cache-Control Directives Cache-control directives define how a CDN caches responses. DataGraph supports the following cache-control directives: - `private`: Indicates that the response can be stored only in a private cache, for example, in the local cache in a browser. - `public`: Indicates that the response can be stored in a shared cache. - `max-age`: Indicates that the response remains fresh until _n_ seconds after the response is generated. - `no-cache`: Indicates that the response can be stored in caches, but that it must be validated with the origin server before each reuse. - `no-store`: Indicates that neither private nor public caches should store the response. The following example cache-control header indicates that a response can be stored in a shared cache for 10 minutes: `“Cache-Control:public, max-age=600”` ### Dynamic Cache-Control in DataGraph DataGraph automatically selects the most restrictive value of cache-control headers from the APIs that are used to resolve the fields in a persisted query. For example, consider a query that contains fields from two APIs, each of which has a different `max-age` value: API-1 has a `max-age` of 300 seconds, and API-2 has a `max-age` of 500 seconds. The `max-age` header value for the query response automatically selects the `max-age` of the two APIs, 300 seconds. ### Request a Persisted Query from a CDN To request a persisted query from a CDN, ensure that you have: - The DataGraph Consume permission. - An authenticated passthrough connection to DataGraph using a valid client ID and secret. You can configure your CDN to add these credentials when passing a request to DataGraph, or you can add the credentials headers on the allowlist of the route to DataGraph. - Permissions to request content from or authenticate to your CDN. - The endpoint to the CDN you’re requesting the query from? > [!IMPORTANT] You must configure your CDN to pass the following query parameters: `extensions`, > `variables`, `operationName`, and `query`. To request a persisted query from a CDN, create a GET request that contains the following: - The endpoint to the CDN - An extension that contains the `persistedQuery` parameter - A hash ID within the persistedQuery parameter The following example shows how to request a persisted query from a CDN using curl: ```copy curl --location --request GET 'https:///graphql?extensions=%7B%0A%20%20%22persistedQuery%22%3A%20%7B%0A%20%20%20%20%22version%22%3A%201%2C%0A%20%20%20%20%22sha256Hash%22%3A%20%22acf31818e50ac3e818ca4bdbc433d6ab73176f0b9d5f9d5ad17e200cdab6fba4%22%0A%20%20%7D%0A%7D' ``` ## See Also - [Supported Authentication Methods](https://docs.mulesoft.com/datagraph/security#supported-authentication-methods) - [Using Permissions for Anypoint DataGraph](https://docs.mulesoft.com/datagraph/permissions) --- product: DataGraph --- # Using Permissions for Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint DataGraph provides access management permissions so you can meet your organization’s security requirements and at the same time drive collaboration across teams. Permissions for Anypoint DataGraph are independent of permissions for other Anypoint Platform products. To contribute to the unified schema, you need to have the **Exchange Viewers** permission for the business group from which you want to add APIs. Refer to [Set User Access Permissions](https://docs.mulesoft.com/exchange/to-set-permissions) for more information. The following permissions are available per business group per environment:
PermissionDescription

Admin

Permission to:

  • Contribute, consume, and operate the unified schema

  • View usage metrics

Contribute

Permission to:

  • Add source APIs to the unified schema

  • Edit any source API schema added to the unified schema

  • Request access to run queries

  • Promote API schemas to an environment

  • View query traces in real time while running queries from the UI

  • Download a copy of the unified schema from the query editor

Consume

Permission to:

  • View and explore the unified schema

  • Request access to run queries and make data requests from the UI

  • Download a copy of the unified schema from the query editor

Operate

Permission to:

  • View customer-facing logs

  • Set a dedicated load balancer URL for Anypoint Datagraph

## Additional Resources - For more information on setting Anypoint DataGraph SLA tiers and managing contracts, refer to [DataGraph Administration](https://docs.mulesoft.com/api-manager/latest/datagraph-landing-page) in the API Manager documentation. - For instructions on setting up user permissions and roles for Anypoint DataGraph, refer to [Granting Permissions and Roles to Users](https://docs.mulesoft.com/access-management/users#granting-permissions-and-roles-to-users) --- product: DataGraph --- # Viewing Status Updates in Anypoint DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt When working with APIs and the unified schema, status updates let you know when the unified schema is available for querying, when changes to the unified schema have taken effect, and which API schemas are getting added, removed, or updated. ## Status: Updating You can add to and update the unified schema at any time. After you apply changes, the status reads **Updating** and indicates the progress and queued updates. This status update is visible to anyone in your business group who has permissions for the environment. ![Status indicator shows adding API schema to unified schema](/mulesoft/current/en-us/datagraph/_images/datagraph-status-update-in-process.png) When the unified schema is updating, you can view the new changes in the schema, make additional changes, and apply new changes. However, these changes aren’t available to query until the update is complete. As queued updates finish, the status changes to **finished**. ![Status indicator shows an update is finished](/mulesoft/current/en-us/datagraph/_images/datagraph-status-update-finished.png) When all updates are complete, the status changes to **Up to date**. ![Status indicator shows unified schema is up to date](/mulesoft/current/en-us/datagraph/_images/status_uptodate.png) ## Status: On hold In the case that Anypoint DataGraph is unreachable, the status will change to **On hold**. If you were attempting any changes, Anypoint DataGraph will automatically apply those changes when it’s available, and the status will change to **Updating**, with details of which APIs are being added, removed, or updated. When the status is **On hold**, you can continue to browse the unified schema and source list, but you can’t make any edits. You can also run queries against the previously deployed unified schema. ## Fixing Update Conflicts As you make changes to existing API schemas or add them to the unified schema, Anypoint DataGraph automatically updates the unified schema’s metadata. This happens instantaneously, and the updated metadata is stored near real-time. You may, however, encounter rare cases when there are errors with the metadata—for example, when another contributor applies a conflicting change at the same time. In such cases, you must ensure you have the latest version of the unified schema and then re-attempt your change. --- product: DataGraph --- # Viewing Usage Metrics for Anypoint Datagraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Anypoint Datagraph provides API request metrics, and you can view additional usage metrics for DataGraph in Anypoint Monitoring. ## View API Request Metrics DataGraph enables you to track metrics so you’re always aware of your usage relative to the limits specified for your business groups. Use these metrics to track the total number calls made to the unified schema in each environment. Usage metrics are separated by Production and Sandbox environments per business group. More specifically, the metrics in any given environment show: - GraphQL API requests received for that environment - GraphQL API requests received for other environments of that type - GraphQL API requests received for all environments of that type > [!NOTE] These metrics are specific to Anypoint DataGraph and reflect GraphQL API requests to the > unified schema only. They do not represent general Mule application traffic or VPC-level network > metrics. Cross-environment aggregation here is a DataGraph-specific feature and is not available > for general application or VPC traffic in Anypoint Monitoring. API request usage metrics are available in the Overview section of Anypoint DataGraph. To view usage metrics, you need the [Admin permission](https://docs.mulesoft.com/datagraph/permissions). 1. Click Overview. 2. Click Details and confirm you’re in the correct environment. 3. Click Usage Metrics. ![DataGraph usage metrics are shown in the Overview section](/mulesoft/current/en-us/datagraph/_images/datagraph-usage-metrics.png) 4. To see metrics for a specific time period, set the calendar parameters. The metrics query runs automatically and updates the data. 5. To refresh the metrics for the current time period, click the refresh icon. ## View Usage Metrics with Anypoint Monitoring Anypoint Monitoring enables you to view usage metrics via built-in dashboards and custom dashboards. These metrics relate to calls made to your DataGraph application, not to calls made to APIs federated in your unified schema. ### Built-in Dashboards In Anypoint Monitoring, DataGraph is considered a "managed API". You select the environment and the name of your DataGraph application when you [view built-in dashboards](https://docs.mulesoft.com/monitoring/anypoint-insights#view-a-built-in-dashboard). Built-in dashboards require no configuration and include various pages to view different types of charts. For example, the overview page includes data related to: - Request volume - Failed requests - Total 4xx errors - Total 5xx errors - Average response time ### Custom Dashboards Custom dashboards collect the same metrics as built-in dashboards. They require additional configuration and are useful for: - Correlating diverse metrics - Performing comparative analysis - Differentiating between regular trends and anomalies - Isolating issues quickly The following example shows how to set up a custom dashboard to track request volume by client\_id. 1. From Anypoint Monitoring, select **Custom dashboards**. 2. Click **+New Dashboard**, add then select the graph option. 3. On the new graph, click the configure menu (the vertical ellipses), and then click **Configure**. 4. Switch the **Advanced Mode** toggle to activate advanced mode. 5. Edit the query as follows: 1. In the **Panel Type** drop-down list, select **API Panel**. (Datagraph is an API application type.) 2. Next to **Where**, click **+**. 3. From the drop-down lists, select `api_id` and `api_version_id` and set the value for each to the Datagraph application from which you’re collecting info. 4. From the **Select** drop-down list, select `field(request_size.count)`. 5. From the **Group by** drop-down list, select `tag(client_id)`. 6. In the **Alias by** field, add `$tag_client_id`. 6. Click **Apply changes**. 7. Open the time-picker, choose a timeframe, and click **Confirm**. The following example shows a graph tracking requests over the previous hour: ![A custom Monitoring graph showing request volume by client\_id](/mulesoft/current/en-us/datagraph/_images/datagraph-custom-graph.png) ## Additional Resources - [https://docs.mulesoft.com/monitoring/dashboard-custom-config](https://docs.mulesoft.com/monitoring/dashboard-custom-config) - [https://docs.mulesoft.com/monitoring/create-custom-dashboard](https://docs.mulesoft.com/monitoring/create-custom-dashboard) - [https://docs.mulesoft.com/monitoring/app-dashboards](https://docs.mulesoft.com/monitoring/app-dashboards) --- product: DataGraph --- # Writing GraphQL Queries and Mutations in DataGraph > For the full documentation index, see: https://docs.mulesoft.com/llms.txt This brief tutorial introduces key concepts for writing GraphQL queries in Anypoint DataGraph. Learn how to use the Anypoint DataGraph query editor to: 1. Discover and add a query operation 2. Add input parameters to a query 3. Discover which fields are available to query 4. Add nested types 5. Add a query alias 6. Write a mutation and understand query types ## Discover and Add a Query Operation In GraphQL, query methods serve as the entry points to retrieve the data you want. Start by using the schema explorer in the Anypoint DataGraph query editor to discover which query methods are available for an API schema. For example, the Catalyst Order API schema, used in the [DataGraph quick start guide](https://docs.mulesoft.com/datagraph/datagraph-qsg), has two query methods associated with it: `ordersCustomerByCustomerId` and `ordersByOrderId`: ![Two query methods listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-query-method.png) Consider `ordersByOrderId`: This query method returns data about the object type `OrderResponse` and requires an argument for `orderID` in the form of a string: `ordersByOrderId (orderId:String!):OrderResponse` In GraphQL, you add the query method to start a query: ```copy { ordersByOrderId(orderId:String!) } ``` ## Add Input Parameters Notice that the input parameter for the query method `orderID` is a non-nullable field, as indicated by the exclamation point (`!`). This field requires a string data type that is not a null value. In this case, you need to add an order ID to the query: ```copy { ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") } ``` ## Add Fields Fields represent a type’s dataset that is returned in a query response, and you can choose whatever fields you need when writing a query. For example, as previously mentioned, the `ordersByOrderID` query method returns the `OrderResponse` object type, which returns the following fields: ![Available fields listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-fields.png) As you write a query, you can add or remove any of these fields. The following query a uses some of the available fields: ```copy { ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") { customerId status subtotal taxPrice total trackingNumber } } ``` `OrderResponse` is a Level-1 type, meaning you can access it directly with a query method, as in the previous example. ## Add Fields for Nested Types Many of the fields returned by the OrderResponse object type, such as `billingAddress`, are object types themselves that contain additional data that can make your query result more valuable. These additional types are known as nested types. The `billingAddress` object type returns the `PostalAddress` object type, which itself returns several additional fields. To query `billingAddress`, you must specify which fields to return from `PostalAddress`. For example: ```copy { ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") { billingAddress { state city postalCode } } } ``` As a result, your final query looks like: ```none { ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") { customerId status subtotal taxPrice total trackingNumber billingAddress { state city postalCode } } } ``` For this query, Anypoint DataGraph returns: ```none { "data": { "ordersByOrderId": { "customerId": "1964401a-a8b3-40c1-b86e-d8b9f75b5842", "status": "Draft", "subtotal": "100.21", "taxPrice": "15.22", "total": "125.43", "trackingNumber": "", "billingAddress": { "state": "CA", "city": "San Francisco", "postalCode": "94210" } } } } ``` ## Add a Query Alias You can use aliases to rename individual keys in the query response. For example, you can rename the total field to `totalPrice` and the status field to `orderStatus` in only your query response. ```copy { ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") { billingAddress { state city postalCode } totalPrice : total orderStatus : status } } ``` If you want to get the same fields for two or more query operations using different input parameters, you can provide an alias to the query operations. ```copy { Order1: ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") { billingAddress { state city postalCode } totalPrice : total orderStatus : status } Order2: ordersByOrderId(orderId: "87c0ba4a-de28-12o7-pd11-eew12094b0w4) { billingAddress { state city postalCode } totalPrice : total orderStatus : status } } ``` This helps to avoid errors if the same fields get different values. ## Write a Mutation _Mutations_ are operations you use to add, update, and delete data objects. In GraphQL, mutation operations represent the POST, PUT, PATCH, and DELETE HTTP methods you’ve defined in your REST API specification. To simplify the schema, inputs to mutations are handled by _input types_, which represent the attributes of objects created by mutation operations. Input types are POST, PUT, and DELETE request objects you use to modify information in your unified schema when you run mutations. For example, the schema shown in the following example has six mutation operations associated with it: ![Six mutation operations listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-mutation-method.png) Consider `createCustomer`: This mutation takes the `CustomerInput` object as an input and creates a new object of type `Customer`. So in this case, the input type `CustomerInput` has the following fields: ![Fields for CustomerInput listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-mutation-fields.png) Notice that the address field has data from the `AddressInput` input type: ![Fields for AddressInput listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-mutation-fields2.png) As you execute the mutation operation, you provide a value for each field in the input type: ```copy mutation { createCustomer(input: { firstName: "Lydia", lastName: "Millet", address: { city: "Tucson", state: "Arizona", street: "Speedway", postalCode: "1234" } }) { id } } ``` Because this mutation creates a new customer, DataGraph returns the following: { "data": { "createCustomer": { "id": 42 } } } Note that the `CustomerInput` input type does not have an `id` field, so the mutation doesn’t include that field in the input to the mutation. However, the `Customer` type includes an `id` field, the value of which is generated based on the values provided in the input. ## Additional Resources - [GraphQL Query Documentation](https://graphql.org/learn/queries/) - [Anypoint DataGraph Terminology](https://docs.mulesoft.com/datagraph/datagraph-terms) - [Understanding the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas) - [Running Queries and Mutations](https://docs.mulesoft.com/datagraph/query-unified-schema)