Registered APIs

Registered APIs are a new technology coming soon to Globus Flows that will make it possible to interact directly with existing APIs, without the need to host an action provider.

Globus subscribers will be able to register and share APIs for use in Flows. Flow authors can call them in their flow definitions as easily as action providers.

Use Cases

Registered APIs can be used to incorporate new service functions into your flows without the overhead of creating and maintaining a long-lived intermediary service (an action provider). For example, registered APIs can provide access to APIs for HPC systems inside of flows, enabling smarter scheduling of tasks with just-in-time evaluation of queue depth or capacity. Registered APIs can also be used to provide access to an instrument from within a flow, or to provide access to resources previously only available through third-party APIs.

Registering an API

Registered APIs support services that use Globus Auth for authentication, as well as unauthenticated APIs.

Registered APIs support JSON APIs that use OpenAPI to document their request and response schemas. Customized OpenAPI schemas may also be provided directly when registering an API, for instance in the case that a service does not provide an official OpenAPI definition at a well-known location.

All Globus subscribers will have access to the ability to register APIs, including APIs for which they’re not the service owner. A dedicated CLI tool, the Globus Registered API CLI, will launch alongside availability in the Flows service to facilitate registration.

Using Registered APIs

Handlers

To use a registered API in an action in your flow definition, you specify it using a handler. Handlers are a new way of specifying the execution method for a given action, and they’re compatible with both action providers and registered APIs.

For instance, to specify the "Transfer - Stat" Action Provider as your action’s handler, you could specify the ActionProvider handler type and provide its URL in your flow definition:

{
  "StartAt": "CheckFile",
  "CheckFile": {
    "Type": "Action",
    "Handler": {
      "Type": "ActionProvider",
      "Url": "https://transfer.actions.globus.org/stat"
    },
    "Parameters": {
      "endpoint_id.$": "$.endpoint_id",
      "path.$": "$.path"
    },
    "ResultPath": "$.output",
    "End": "True"
  }
}

A registered API can similarly be called by using the RegisteredAPI handler type and specifying its ID:

{
  "StartAt": "CheckFile",
  "CheckFile": {
    "Type": "Action",
    "Handler": {
      "Type": "RegisteredAPI",
      "Id": "36fd9be5-e5ab-465e-b98f-d727b4770787"
    },
    "Parameters": {
      "endpoint_id.$": "$.endpoint_id",
      "path.$": "$.path"
    },
    "ResultPath": "$.output",
    "End": "True"
  }
}

Handles

To promote readability, and for easier reference, a registered API may be associated with a handle, of the format:

urn:globus:flows:handle:<organization>:<api-name>

For example, the Globus Search "Get Entry" registered API uses the handle:

urn:globus:flows:handle:globus:search.get-entry

In this case, the organization is globus and the API name is search.get-entry. Similarly, the Globus Groups "Get Group" registered API uses the handle:

urn:globus:flows:handle:globus:groups.get-group

When calling a registered API in a flow, one can specify its handle instead of the ID:

{
  "StartAt": "CheckStatus",
  "CheckStatus": {
    "Type": "Action",
    "Handler": "urn:globus:flows:handle:my-org:our-hpc.queue-status",
    "Parameters": {},
    "ResultPath": "$.output",
    "End": "True"
  }
}

In a future release, it will be possible for subscription managers to create handles and assign them to registered APIs that are associated with their subscription.

Format

Registered APIs make it possible to provide data for multiple different elements in a request. For example:

{
  "StartAt": "CallAPIDirectly",
  "CallAPIDirectly": {
    "Type": "Action",
    "Handler": {
      "Type": "RegisteredAPI",
      "Id": "36fd9be5-e5ab-465e-b98f-d727b4770787"
    },
    "Parameters": {
      "body": {
        "my_param": 1
      },
      "path": {
        "resource_id": "$.my_id"
      }
    },
    "ResultPath": "$.output",
    "End": "True"
  }
}

In a future release, data templates will also enable further customization of a registered API’s requests and responses, allowing for streamlined interfaces inside of flow definitions.

Additional Information

Registered APIs currently support non-blocking interactions. This means they will emit a request to an API, place the response into the run’s state, and proceed to the next state in the flow. They do not yet intrinsically support blocking the run until a resource in an external service reaches a particular state—for example, waiting for a transfer task to finish. For actions that need to block awaiting the status of a resource in an external service, action providers remain the recommended solution.

Availability

Registered APIs will be available in an upcoming release of Globus Flows. Creation of registered APIs will be available to Globus subscribers. All Globus users are able to use registered APIs in their flow definitions and run flows with actions that reference registered APIs.