Patterns and Key Concepts

• All service methods return a Promise that resolves to a Fetch API Response object.
  • Under the hood, we are returning the result of a composed fetch.
• All service methods accept a ServiceMethodOptions object to pass query parameters, a payload, and headers.
• All service methods support a tail argument to pass options to the SDK, including the composed fetch call.

Service Method Names

Basic CRUD operations provided by services are exposed as the following:

Methods that do not map to obvious CRUD operations are named according to the resource. i.e., groups.groups.getMyGroups(), transfer.endpointSearch(), search.query.post()

// @example Using the SDK to search for endpoints via Transfer API.

import { transfer } from "@globus/sdk";
const result = await (
  await globus.transfer.endpointSearch(
    {
       query: { filter_fulltext: "Globus Tutorial" }
       headers: {
         Authorization: "Bearer MY_ACCESS_TOKEN",
       },
    },
    {
      fetch: {
        // Provide parameters to the underlying `fetch` call.
        // https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters
        options: {
          priority: "high"
        },
      },
    }
  )
).json();
Copy

// @example Using the SDK to fetch a single flow from the Flows API.
import { flows } from '@globus/sdk';
const result = await (await flows.flows.get('452bbea3-5e3b-45a5-af08-50179839a4e8')).json();
Copy

Authorization

While all methods support passing of headers and direct modification of the underlying fetch call, the SDK provides an AuthorizationManager that can be used to manage access tokens and handle the authorization process.

// @example Using the AuthorizationManager with a service method.
import { transfer, authorization } from "@globus/sdk";
const manager = authorization.create({ ... });
const result = await (
  await globus.transfer.endpointSearch(
    {
       query: { filter_fulltext: "Globus Tutorial" },
       manager
    }
  )
).json();
Copy

Service Version Support

Some Globus services expose multiple API generations. The SDK surfaces these under a version namespace on the service object (e.g, transfer.v2).

import { transfer } from '@globus/sdk';

await transfer.v2.bookmarks.getAll();
await transfer.v2.bookmarks.get({ bookmark_id: '...' });
await transfer.v2.bookmarks.create({ request: { data: { name, endpoint_id, path } } });
await transfer.v2.bookmarks.update({ bookmark_id: '...', request: { data: { name } } });
await transfer.v2.bookmarks.remove({ bookmark_id: '...' });

// Service-specific imports are also available.
import { bookmarks } from '@globus/sdk/tranfer/v2';
import { getAll } from '@globus/sdk/tranfer/v2/bookmarks';
Copy

As of v6.x.x the methods on the default namespace may access mixed version usage (service and resource dependent). This default namespace will likely be removed, or more formally aliased to the "latest" version of a service resource in an upcoming major release (breaking change).