Register your first API

Once you’ve followed the tutorial to install GRA and log in, you’re ready to publish your first Registered API!

This tutorial will guide you through the steps necessary to publish a single Registered API that can list your flows in the Globus Flows service.

1. Initialize the repository

The Globus Registered API CLI needs a place to store its configuration, so the first step is to create a new directory, called list-flows-demo, and change directories into it:

mkdir list-flows-demo
cd list-flows-demo

Start repository initialization by running the gra init command:

gra init

We’ll answer the prompts in order.

 Initializing GRA Repository
  >  1. Set Subscription
     2. Set OpenAPI Location
     3. Set Base URL
     4. <Cancel>

Use the arrow keys to select the "Set Subscription" option and press [ENTER]. A Globus subscription is required to create Registered APIs, and the subscription you select here will be associated with the Registered API that you create in this tutorial.

The Globus subscriptions you have access to will be presented in a list. If you have more than one, select the subscription that you want to use. You’ll be returned to the initialization menu.

 Initializing GRA Repository
     1. Set Subscription ('My Globus Subscription')
  >  2. Set OpenAPI Location
     3. Set Base URL
     4. <Cancel>

Select the "Set OpenAPI Location" option and press [ENTER] to set the location of the OpenAPI document. For this tutorial, use the URL of the Globus Flows OpenAPI specification, which contains the "list-flows" target that we want to register:

https://globusonline.github.io/globus-flows/flows.openapi.json

Copy and paste that URL into the terminal and press [ENTER]. You’ll be returned to the initialization menu:

 Initializing GRA Repository
     1. Set Subscription ('My Globus Subscription')
     2. Set OpenAPI Location ('https://globusonline.github.io/globus-flows/flows.openapi.json')
  >  3. Set Base URL
     4. <Cancel>

Finally, select the "Set Base URL" option and press [ENTER] to set the service base URL.

The Globus Flows OpenAPI specification lists two service base URL; select the first, https://flows.globus.org/, and press [ENTER]. You’ll be returned to the initialization menu, which now has a new option, <Submit>, because all required questions have been answered.

 Initializing GRA Repository
     1. Set Subscription ('My Globus Subscription')
     2. Set OpenAPI Location ('https://globusonline.github.io/globus-flows/flows.openapi.json')
     3. Set Base URL ('https://flows.globus.org/')
  >  4. <Submit>
     5. <Cancel>

Select option #4 and press [ENTER] to finalize initialization.

There is now a .globus_registered_api/ subdirectory in the list-flows-demo/ directory that you created. It is recommended that you commit this directory and its files to a version control system, like git.

2. Add a target

For this tutorial, we’re going to define a target that refers to the "list-flows" (/flows (GET)) API.

First, run this command:

gra manage

The gra manage command is an interactive menu-based tool. Note that the screens shown below may differ slightly, but the goal remains the same: registering the /flows (GET) route as new target.

You will see a basic menu with arrow-key navigation controls:

 Main Menu
  >  1. Manage Targets
     2. Manage Roles
     3. Manage Stages
     4. <Exit>

Select "Manage Targets" from the menu and press [ENTER], and you’ll see this list of options related to targets:

 Main Menu > Manage Targets
  >  1. <Register a New Target>
     2. <Back>
     3. <Exit>

Select "Register a New Target" from the menu and press [ENTER]. You’ll see a screen like this:

 Main Menu > Manage Targets > Add Target
  >  1. Select Route
     2. Set Alias
     3. Set Description
     4. Set Globus Scope
     5. <Cancel>

Notice that there is no "Submit" option! You’ll need to provide a response to each of the listed settings first.

Select the "Select Route" option and press [ENTER]. You’ll be presented with a list of API routes like this:

 Select an API Route:
     1. <Enter custom path and method>
     2. /batch/runs (POST)
  >  3. /flows (GET)
     4. /flows (POST)
     5. /flows/validate (POST)
     6. /flows/{flow_id} (DELETE)
     7. /flows/{flow_id} (GET)
     8. /flows/{flow_id} (PUT)
     9. /flows/{flow_id}/run (POST)
     ...

Select the /flows (GET) route, which is #3 in the example above, and press [ENTER]. You’ll be returned to the "Add Target" menu:

 Main Menu > Manage Targets > Add Target
     1. Select Route ('/flows (GET)')
  >  2. Set Alias
     3. Set Description
     4. Print Globus Scopes (OpenAPI)
     5. <Cancel>

Select the "Set Alias" option and press [ENTER].

Aliases are human-readable names for the combination of the HTTP method and API path. For this tutorial, type list-flows as the alias and press [ENTER]. You’ll be returned to the "Add Target" menu:

 Main Menu > Manage Targets > Add Target
     1. Select Route ('/flows (GET)')
     2. Set Alias ('list-flows')
     3. Set Description ('Retrieve all Flows')
     4. Print Globus Scopes (OpenAPI)
  >  5. <Submit>
     6. <Cancel>

Notice the description has already been filled in because it was present in the OpenAPI specification. You are free to modify the description if desired.

However, the Globus Flows OpenAPI specification also defines the target’s Globus scopes. The GRA CLI does not allow users to modify the target’s Globus scopes if the OpenAPI document defines scopes…​and the Globus Flows OpenAPI document does define scopes.

No additional changes are needed to continue this tutorial, so select the "Submit" option and press [ENTER].

The "Manage Targets" menu will be displayed again, with the new "list-flows" target now present:

 Main Menu > Manage Targets
     1. <Register a New Target>
     2. list-flows ('GET /flows')
  >  3. <Back>
     4. <Exit>

Select the "Back" option and press [ENTER] to return to the Main menu.

3. Review roles

By default, only your Globus Auth identity will have access to the Registered APIs that you publish. That’s sufficient for the purposes of this tutorial, but let’s take a moment to see the default role that’s defined.

 Main Menu
     1. Manage Targets
  >  2. Manage Roles
     3. Manage Stages
     4. <Exit>

At the main menu shown above, select the "Manage Roles" option and press [ENTER]. Similar to the "Manage Targets" menu, you’ll see a number of menu options that let you review and edit the roles that will be assigned to all the Registered APIs you define:

 Main Menu > Manage Roles (production)
     1. <Register a New Role>
  >  2. Manage 'user@globusid.org' (Owner)
     3. <Back>
     4. <Exit>
Note

It is strongly recommended that you give Owner access to a Globus group with two or more members! This will help prevent loss of management access to the Registered APIs that you create.

It is also recommended that you use a version control system like git and provide repository access to the same users that have owner access to the Registered APIs.

Select "Exit" from the menu and press [ENTER].

4. Build and publish

Now that a target has been added, and roles have been reviewed, it’s time to build and publish the repository to the Globus Flows service!

First, build the repository by running the gra build command:

$ gra build
Successfully computed manifest artifact
Wrote manifest to disk:
  /path/to/list-flows-demo/.globus_registered_api/manifest.json

Next, run the gra publish command and confirm that you want to proceed:

$ gra publish
The following targets will be published:
  - list-flows (create)
Would you like to proceed? [y/N]:

You’ll see output similar to this:

Creating 'list-flows'...
  Created with ID: 00000000-0000-0000-0000-000000000000

Successfully published 1 target(s).

Copy the Registered API ID. You’ll need it for the next part of the tutorial!

If you lose track of the list-flows Registered API ID, you can use the gra api list command to find it again:

$ gra api list
ID                                   | Name
-------------------------------------|-----
00000000-0000-0000-0000-000000000000 | list-flows

5. Recap

In this part of the tutorial, you’ve worked through

  • Initializing a new Globus Registered API repository

  • Defining a target

  • Reviewing the roles that will be assigned to all the Registered APIs

  • Building and publishing the Registered API to the Globus Flows service

6. Next Steps

Remember to copy the newly-created Registered API ID; in the next part of the tutorial you’ll actually use it in a flow.

Next Tutorial: Use a Registered API in a Flow