Nav

API Auto-Discovery

You include API auto-discovery capability in a Mule application to enable API management from Anypoint Platform on the application HTTP endpoint. API Management includes tracking and shows the API status, enforcing policies if you apply any, and reporting API analytics.

You can include the code shown in the auto-discovery reference in your Mule app, or you can use Studio to incorporate auto-discovery in your project. When you run an app that incorporates auto-discovery, the auto-discovery process registers and starts the app in API Manager. Registration and start up occurs without user intervention.

Studio Configuration

To use API auto-discovery, first you need to pair Anypoint Studio with an Anypoint Platform organization by adding organization credentials to Studio Preferences. Next, you configure auto-discovery for each flow you want to manage using a global element. A Global Element contains the necessary information for registering your API to the Anypoint Platform. Global Elements must then be referenced by one or more endpoints. Finally, you deploy the API project as a Mule application in Studio. API Manager discovers the API and registers it. The API appears on the API Administration page in Anypoint Platform for each flow you configure for auto-discovery.

To configure and trigger auto-discovery:

  1. In a browser, log in to the Anypoint Platform as an administrator, click Access Management. Select Organization.

    Select your Organization from the list.

    The client ID and client secret appear.

  2. From the Anypoint Studio main menu, select Anypoint Studio > Preferences > Anypoint Studio > Anypoint Platform for APIs.

    The Preferences dialog for Anypoint Platform for APIs appears.

  3. Copy the client ID and client secret from step 2 to Client Credentials.

    autodis-pairing

    This action pairs Mule Runtime with your Anypoint Platform organization.

  4. Click Validate to verify that the pairing succeeds.

  5. Click OK.

  6. In Project Explorer, select the app. For example, select api.xml in src/main/app that you created in the APIkit tutorial.

  7. On the Global Elements tab on the canvas, click Create.

    autodis-create-global2

    The Choose Global Type dialog appears.

  8. Select Component configurations > API Autodiscovery.

    The Global Element Properties - API Autodiscovery dialog appears.

  9. Create a global element to declare the details of the API version you want Anypoint Platform to discover:

    • In API Name, type an arbitrary name, for example vending.

      If you are creating a new API, API Manager makes this name visible in Anypoint Platform.

    • In API Version, type an arbitrary version identifier, for example 1.0development.

      Do not change the version name later in API Portal, as explained in "Best Practices".

    • In Flow Name, select the name of the flow in the API from the drop-down. Select the flow that you want to which you want to direct requests. For example, select api-main, the APIkit tutorial main flow.

    • Check the option to automatically create an API if it doesn’t exist.

    • In APIkit Router Configuration, click api-config from the drop-down in the case of the APIkit tutorial.

      This configuration is not used by API Manager.

    • In Description, write some documentation about the API.

      auto-disc-conf2

    • Click OK.

  10. In Project Explorer, right-click the app, api.xml in this example, and select Run As > Mule Application.

    In a few moments, the API appears on the API Administration page of Anypoint Platform.

    autodisc-discovered2

    You need to be a member of the Organization Administrators or API Versions Owner role to see a newly registered API in Anypoint Platform.

Auto-discovery on CloudHub

If you use the Deploy to Anypoint Platform > Cloud context menu to deploy an API or proxy with auto-discovery to the Anypoint Platform, CloudHub automatically replaces 0.0.0.0:${http.port} in your endpoint with <YourUniqueDomain>.cloudhub.io and sends this endpoint URL to the API Manager to be displayed and tracked by the agent.

If your endpoint runs over HTTP, use the variable http.port in its address. If the endpoint runs over HTTPS, use the variable https.port instead.

Configuring and Using Auto-Discovery - API Gateway Runtime 2.x

To set up an API for auto-discovery, you first install an API Gateway Runtime. For example, install API Gateway Runtime 2.2.0. Next, follow the procedure in the previous section to configure and use auto-discovery.

Auto-discovery Process

The following diagram illustrates the auto-discovery process for a project containing an api-platform-gw:api auto-discovery global element in the configuration.xml:

api-auto-discovery-v2

After API registration, the API version and its endpoint function the same as any other API version or endpoint. You can edit, update, or delete the API. If the Mule runtime or API Gateway runtime instance running the API goes offline, or you stop the underlying application, the API and endpoints remain in API Manager, but the endpoints are untracked by the agent.

Configuring and Using Auto-Discovery - API Gateway Runtime 1.3.2 or Earlier

As of version 1.3 of the API Gateway runtime, if you need your endpoint to be tracked, include the required attributes in the global element in the configuration.xml, and reference the global element in the inbound endpoint.

If you’re using the APIkit Studio extension, you can reference the API’s RAML definition file to trigger auto-discovery. You cannot subsequently manage the endpoint using this method, however.

Best Practices

Perform the following tasks after using auto-discovery to deploy an API:

  • API auto-discovery registers new APIs, API versions, and/or endpoints. If the API already exists, the agent does not compare the name, description, tags, or any other information contained in the global element for updates.

  • After you have registered new APIs or versions using auto-discovery, visit Anypoint Platform and add the necessary API Versions Owner permissions so that users who need to access the API version details page for this API version can get there.

  • Set the endpoint host to 0.0.0.0 instead of localhost.

  • Do not change the API Version name in API Portal if you have used auto-discovery. Doing so will break management of the API/