salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. DataGraph

  3. Adding API Sources to the Unified Schema

Adding API Sources to the Unified Schema

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 for more information.

Adding an API to the unified schema comprises three tasks:

  1. Add the API to Anypoint DataGraph

  2. Preview the generated API schema

  3. Edit the API schema and resolve any conflicts

    You must resolve any conflicts between object types before adding the generated API schema to the unified schema. Refer to Resolve Conflicts for more information.

After you add an API, you can:

You can also use the Anypoint 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 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.

  • 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 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 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 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 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 that you add to the unified schema to make them more relevant for queries.

    • Merge similar object types.

      Merging types enables you to combine similar types to extend their fields and datasets for more enriched query results.

    • Link related fields between object types.

      Linking 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. 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.

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.

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