1. Overview

Endpoints are identified by a non-globally-unique name, called the display_name. They are uniquely identified by an id (and for legacy support by a canonical_name, but this will be removed in the future). Since names are no longer globally unique, a search interface is needed to help users find endpoints.

The search matches against the following fields:

  • display_name

  • canonical_name

  • description

  • organization

  • department

  • keywords

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

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).

The limit query parameter sets how many results to return (max 100), and the offset parameter sets where to start within the total results set for paging (max 999).

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 administered by the current user, which does not require the "administrator" role on the host endpoint.

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 shared endpoints owned by the current user.

False

shared-with-me

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

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


© 2010- The University of Chicago Legal