Endpoint and Collection Search

1. Overview

Endpoint and Collection search is the primary mechanism for discovering Endpoints and Collections for use with the Globus Transfer API. Once discovered, Endpoints and Collections are identified by a unique id when using other Transfer API resources.

The search matches against the following fields in the endpoint or collection document

  • display_name

  • canonical_name

  • description

  • organization

  • department

  • keywords

  • owner_string

In addition, GCSv5 endpoints and collections will be matched against their domain name.

The search will be run against all endpoints owned by the current user (both public and private), and all public endpoints owned by other users.

Results will be sorted based on how well the query matches the endpoint and the priority of the matching fields.

2. Document Types

See Endpoint or Collection Document.

3. Common Query Parameters

Name Type Description

fields

string

Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed.

4. Common Errors

Code HTTP Status Description

ServiceUnavailable

503

If the service is down for maintenance.

5. Operations

Get a list of endpoints matching the search filters in a given search scope.

The filter_fulltext query is processed and matched as follows:

  1. remove punctuation

  2. split query into terms, using space as the separator

  3. canonicalize words using English dictionary, remove plurals and stop words

  4. AND all terms

  5. Look for endpoints with one of the fields described above matching all terms, in any order and location. A term will match if it matches the beginning of a word or the entire word (prefix based matching).

This resource uses offset paging, and includes a has_next_page boolean in the response body.

URL

/endpoint_search?filter_fulltext=QUERY&filter_scope=SCOPENAME&filter_owner_id=IDENTITY_ID&limit=N&offset=M

Method

GET

Response Body

 
{
    "DATA_TYPE": "endpoint_list",
    "offset": 0,
    "limit": 100,
    "has_next_page": false,
    "DATA": [
        {
          "DATA_TYPE": "endpoint",
          ...
        },
        ...
    ]
}

5.1.1. Query Parameters

Query Parameter Type Default Description

offset

int

0

Zero based offset into the result set, used for paging. Note that if the results change between requests, e.g. if new endpoints are added or existing endpoints are renamed, this may return duplicate results across pages or skip results that existed when the original request was made. Max 999.

limit

int

25

Maximum number of results to return. The maximum allowed limit is 100.

filter_scope

string enum

all

String indicating which scope/class of endpoints to search. See the Search Scope section below for details. Default "all".

filter_fulltext

string

null

Match endpoint fields against this string, as described in detail above. This is required if the filter_scope is "all", otherwise it’s optional.

filter_owner_id

string

null

Limit search to endpoints owned by the specified Globus Auth identity. See also the owner_id field of the endpoint document. To get a list of the user’s own endpoints, use filter_scope "my-endpoints" instead. Conflicts with scopes "my-endpoints", "my-gcp-endpoints", and "shared-by-me".

filter_owner_username

string

null

[DEPRECATED] Use filter_owner_id instead. Limit search to endpoints owned by the specified globusid.org user, identified by username. See also the username field of the endpoint document.

filter_host_endpoint

string

null

Single endpoint id. Limit search to endpoints hosted by the specified endpoint. "BadRequest" will be returned if the specified endpoint does not support hosting shared endpoints. "PermissionDenied" will be returned if the user does not have the "administrator" effective role on the specified endpoint. See Get shared endpoint list for getting a list of shared endpoints which does not require the "administrator" role on the host endpoint.

filter_non_functional

boolean

null

1 for True, 0 for False. Limit search to endpoints which have their non_functional flag set to True or False respectively. Mutually exclusive with filter_entity_type.

filter_entity_type

string

null

Limit search to endpoints or collections by their entity type. See Entity Types for a list of supported entity types. See also the entity_type field of the endpoint document. The search scopes "shared-by-me" and "shared-with-me" will limit search results only to relevant GCSv5 guest collections and GCP guest collections. The search scope "my-gcp-endpoints" will limit search results only to relevant GCP entity types. Mutually exclusive with filter_non_functional.

5.1.2. Search Scope

The optional filter_scope query parameter can be used to further restrict the endpoints searched. The supported values and their affect are described below. Note that some scopes require that another filter parameter also be specified (see the list above), while others do not.

Value Description Additional Filter Required

all

Search all endpoints visible to the current user. This is the default.

True

my-endpoints

Search only endpoints owned by the current user.

False

my-gcp-endpoints

Search only Globus Connect Personal endpoints owned by the current user.

False

recently-used

Search endpoints used recently by the current user.

False

in-use

Search endpoints that have an active task owned by the current user.

False

shared-by-me

Search guest collections for which the current user has the "administrator" or "access_manager" role.

False

shared-with-me

Search shared endpoints with permissions that give the current user access. Does not include rules with public or all_authenticated_users access or implicit permissions from roles.

False

administered-by-me

Search only endpoints for which the current user has the "administrator" role (this includes endpoints owned by the current user, so this is a superset of scope "my-endpoints").

False