Endpoints and Collections

1. Overview

Endpoints and Collections are entities in Transfer that represent part of a Globus Connect Server or Globus Connect Personal installation. They are identified by a globally unique id, and collections provide access to data on their underlying filesystem either through synchronous File Operations or asynchronous Task Submission.

Globus Connect Server endpoints and collections are read only in Transfer, and can be managed by the Globus Connect Server Manager API.

Globus Connect Personal collections are managed by the Transfer API, see the Globus Connect Personal Management Document.

For information on how roles delegating aspects of the endpoint’s administration to other users, and operations for managing them on Globus Connect Personal endpoints, see Roles.

For managing Access to guest collections (including Globus Connect Server guest collections), see: Guest Collection Permission Management

For searching endpoints and collections by name or other categories, see Endpoint and Collection Search.

1.1. Subscribed Endpoints and Collections

Premium features, such as creating guest collections and using the Advanced Collection Management resources, require a Globus subscription.

Users must be members of a Globus subscription group to associate a subscription with an endpoint or collection. Subscription group managers and administrators do not need to have any effective roles on an entity to associate or dissociate it with their subscription, but the entity must either be unsubscribed or already under a subscription they manage to make changes. Endpoint or collection administrators may associate the entity with any subscription they have a subscription group membership for regardless of the entity’s current subscribed status.

For Globus Connect Server, the subscription is associated with the endpoint using the Globus Connect Server Manager API.

For Globus Connect Personal, the subscription is associated with the mapped collection using the Transfer API. The associate a collection with a subscription resource can be used by both collection administrators and subscription managers to associate a Globus Connect Personal mapped collection with a subscription. Collection administrators may also use a collection update with a subscription_id set in the collection document.

Guest collections and Globus Connect Server mapped collections cannot have a subscription associated with them directly, but will inherit the value and premium behaviors from their parent entities.

2. Document Types

2.1. Endpoint or Collection Document

The endpoint or collection document (DATA_TYPE of "endpoint"[1]) represents a single transfer endpoint or collection definition and is returned by both endpoint and collection search and get endpoint or collection by id.

2.1.1. Entity Types

Since the same document is returned for all kinds of Globus Connect Server and Globus Connect Personal endpoints and collections, the entity_type field is used to determine which of those entities the document refers to.

GCP_mapped_collection

These entities represent top level installs of Globus Connect Personal. They are managed in Transfer and do not require additional consent for data access. The gcp_connected field can be used to determine if the Globus Connect Personal client is currently running and connected to Globus.

GCP_guest_collection

This category is made up of guest collections created to share data from a Globus Connect Personal mapped collection. Their host_endpoint_id[1] will be non null and set to the Globus Connect Personal mapped collection. Like Globus Connect Server v5 guest collections access is controlled by permissions created in Transfer.

GCSv5_endpoint

These entities are the top level installation of a Globus Connect Server v5 used for administration and configuration across the installation. They cannot be used for data access, and as such will have non_functional set to "true".

GCSv5_mapped_collection

These entities are used for accessing data via mapping Globus Auth identities to local accounts. They will have a non null non_functional_endpoint_id that refers to their host endpoint. All Globus Connect Server v5 mapped collections will have an authentication_timeout_mins set, and if the high_assurance field is set to "false", then the mapped collection will require a data_access consent before it may be accessed.

GCSv5_guest_collection

Globus Connect Server v5 guest collections are created off a Globus Connect Server v5 mapped collection and are used for sharing access with Globus Auth identities that do not have mappings to local accounts. They will have both a non null non_functional_endpoint_id that refers to their Globus Connect Server v5 host endpoints, and a non null mapped_collection_id that refers to the mapped collection they provide access to. Like Globus Connect Personal guest collections access is controlled by permissions created in Transfer.

GCSv4_host and GCSv4_share

These entity types are no longer supported by the Transfer API.

Endpoint or Collection Document Example
{
  "DATA": [],
  "DATA_TYPE": "endpoint",
  "acl_available": false,
  "acl_editable": false,
  "acl_max_expiration_period_mins": null,
  "activated": false,
  "authentication_assurance_timeout": null,
  "authentication_policy_id": null,
  "authentication_timeout_mins": 15840,
  "canonical_name": "u_eyljfjd6jfg67nm6zp6gly4qpu#e09c6728-80a0-11ee-bddb-c52a29481bea",
  "contact_email": "support@globus.org",
  "contact_info": null,
  "default_directory": "/{server_default}/",
  "department": "Globus",
  "description": "Demo/Tutorial - Managed GCS Host",
  "disable_anonymous_writes": false,
  "disable_verify": false,
  "display_name": "Globus Tutorial Collection 1",
  "entity_type": "GCSv5_mapped_collection",
  "expire_time": null,
  "expires_in": -1,
  "force_encryption": false,
  "force_verify": false,
  "french_english_bilingual": false,
  "gcp_connected": null,
  "gcp_paused": null,
  "gcs_manager_url": "https://b7a4f1.75bc.data.globus.org",
  "gcs_version": "5.4.69",
  "globus_connect_setup_key": null,
  "high_assurance": false,
  "host_endpoint": null,
  "host_endpoint_display_name": null,
  "host_endpoint_id": null,
  "host_path": null,
  "https_server": "https://m-d3a2c3.b7a4f1.75bc.data.globus.org",
  "id": "6c54cade-bde5-45c1-bdea-f4bd71dba2cc",
  "in_use": false,
  "info_link": "https://globus.org",
  "is_globus_connect": false,
  "keywords": "demo,tutorial,globus-tutorial",
  "last_accessed_time": "2023-11-29T00:00:00+00:00",
  "local_user_info_available": true,
  "location": null,
  "mapped_collection_display_name": null,
  "mapped_collection_id": null,
  "max_concurrency": null,
  "max_parallelism": null,
  "mfa_required": false,
  "my_effective_roles": [],
  "myproxy_dn": null,
  "myproxy_server": "myproxy.globusonline.org",
  "name": "e09c6728-80a0-11ee-bddb-c52a29481bea",
  "network_use": null,
  "non_functional": false,
  "non_functional_endpoint_display_name": "Globus Tutorial Endpoint 1",
  "non_functional_endpoint_id": "261692a4-7e49-4def-b59e-cbfc65e3907d",
  "oauth_server": null,
  "organization": "Globus",
  "owner_id": "261692a4-7e49-4def-b59e-cbfc65e3907d",
  "owner_string": "6df1b656-c953-40a3-91a9-e9e8ad5173ea@clients.auth.globus.org",
  "preferred_concurrency": null,
  "preferred_parallelism": null,
  "public": true,
  "requester_pays": false,
  "restrict_transfers_to_high_assurance": null,
  "s3_owner_activated": false,
  "s3_url": null,
  "shareable": true,
  "sharing_target_endpoint": null,
  "sharing_target_root_path": null,
  "storage_type": null,
  "subscription_id": "6cc063b5-89c1-45b9-8167-679c618ec5a3",
  "subscription_admin_verified": false,
  "tlsftp_server": "tlsftp://m-d3a2c3.b7a4f1.75bc.data.globus.org:443",
  "user_message": "This Collection is used for demonstrations and tutorials. It has limited capacity and data may be deleted at any point in time.",
  "user_message_link": null,
  "username": "u_eyljfjd6jfg67nm6zp6gly4qpu"
}

2.1.2. Endpoint or Collection Fields

Field Name JSON Type Description

DATA

array of objects

A list of server documents. Will empty for guest collections and Globus Connect Server mapped collections.

DATA_TYPE

string

Always has value "endpoint"[1].

acl_available

boolean

[DEPRECATED] use entity_type instead to determine if an entity is a guest collection

acl_editable

boolean

[DEPRECATED] use my_effective_roles instead.

acl_max_expiration_period_mins

integer

For High Assurance collections only. Minutes. Determines the maximum lifetime, in minutes, for every ACL inside this collection.

activated

boolean

[DEPRECATED] No longer used by any supported entity types.

associated_flow_policy

object

Specifies that certain Transfer operations on a collection be performed only by a Globus flow. Defaults to null, which implies that no restriction is in effect.

The policy is a series of nested objects.

{
  "transfer": {
    "source": {
      "flow": "<flow ID>"
    },
    "destination": {
      "flow": "<flow ID>"
    }
  }
}

The top level specifies what type of Transfer API operation is being restricted. Currently, the only supported key is "transfer", which corresponds to data transfer in or out of the collection.

The "transfer" object must have one or more keys that specify the direction of data flow being restricted. Supported key names are "source" and "destination".

The structure of the "source" and "destination" objects are the same. There is a "flow" key which specifies the UUID of the Globus Flow which is allowed to submit tasks.

When a flow policy is in place, attempts to submit transfer tasks by other identities will be rejected with an error indicating which Globus Flow should be used to perform the operation.

If both the source and destination collections have flow policies that would apply, the flow IDs must match. For example, if the collection acting as the source in a transfer is configured to restrict source operations to flow A, and the collection acting as the destination is configured to restrict destination operations to flow B, then Transfer will reject the task submission with an error. If both collections specified flow A, then the task would be accepted.

authentication_assurance_timeout

integer

[DEPRECATED] Use high_assurance and authentication_timeout_mins instead.

authentication_policy_id

string

UUID for an authentication policy. Only applies to Globus Connect Server v5 guest collections.

authentication_timeout_mins

integer

This value is the timeout, in minutes, for High Assurance sessions and mapped collection data access. Only Globus Auth identities that have authenticated within the timeout will be used. Note that @clients.auth.globus.org identities are exempt from this timeout.

auto_delete_timeout

integer

The number of days after which a Globus Connect Server guest collection will be deleted automatically due to lack of use, based on last_accessed_time. Attribute is specified on a mapped collection and inherited by its child guest collections. Individual guest collections may be exempted by setting the collection attribute skip_auto_delete to true. Defaults to null, meaning that no automatic deletion policy is in place.

canonical_name

string

[DEPRECATED] Use id and display_name instead.

contact_email

string

Email address of the support contact for the server(s) represented by the entity. ASCII string, must be a valid email address. Optional.

contact_info

string

Other non-email contact information for the entity, e.g. phone and mailing address. Unicode string, can contain new lines, max 4096 characters. Optional.

default_directory

string

Default directory to display when an entity is first accessed in the app.globus.org web interface. The default behavior if not specified depends on entity and connector type, but will typically be the local user’s home directory when available or the root of the collection. Optional.

IMPORTANT The Transfer Endpoint or Collection Document only provides this information for Globus Connect Personal entities (i.e. GCP_mapped_collection and GCP_guest_collection). For other entity types, this is a read-only value set to /{server_default}/. In these cases, the property should be managed via the Globus Connect Server Manager API.

department

string

Department within organization that runs the entity. Unicode string, max 1024 characters, no new lines. Searchable. Optional.

description

string

A description of the entity. Unicode string, max length 4000 characters. Searchable. Optional.

disable_anonymous_writes

boolean

This option indicates that the entity does not allow anonymous write permissions. Any such permissions that already exist will be treated as read only, and attempts to create new anonymous write permissions will raise errors. This option may only be set directly on Globus Connect Server v5 mapped collections, but the flag and behavior will apply to all guest collections whose mapped collection have this set.

disable_verify

boolean

This option indicates that the entity does not support computing MD5 checksums, needed for the verify_checksum option of transfer. When this is set on the entity or a parent, transfer submissions will have checksum verification disabled. Mutually exclusive with force_verify. A task cannot be submitted with source and destination collections that have conflicting disable_verify and force_verify options. Default: see note.

display_name

string

Friendly name for the entity, not unique. Unicode string, max 128 characters, no new lines (\r or \n). Searchable.

entity_type

string

The type of endpoint or collection this document refers to. See Entity Types above for details.

expire_time

string

[DEPRECATED] No longer used by any supported entity types.

expires_in

int

[DEPRECATED] No longer used by any supported entity types.

force_encryption

boolean

If set to true on a collection or a parent entity, all transfer to or from the collection will have the encryption option automatically turned on regardless of the user’s initial submission options. If false, users can decide whether or not to enable encryption. Default: false.

If this is a High Assurance collection, this field will always be true, and updates will be ignored.

force_verify

boolean

If set to true on the collection or a parent entity all transfer submissions will have checksum verification enabled. Mutually exclusive with disable_verify. A task cannot be submitted with source and destination collections that have conflicting disable_verify and force_verify options. Default: see note.

french_english_bilingual

boolean

If this flag is set, notification emails sent by the Transfer service that involve this entity will include both French and English text.

gcp_connected

boolean

For Globus Connect Personal mapped and guest collections, this indicates if the software is running and connected to Globus. For other entity types, this value will be null.

gcp_paused

boolean

For Globus Connect Personal mapped and guest collections, this indicates if the software has paused the connection. For other entity types, this value will be null.

gcs_manager_url

string

For Globus Connect Server v5 endpoints and collections, this value will be the url for that Globus Connect Server v5 installation’s Globus Connect Server Manager API. For other entity types this field will be null.

gcs_version

string

SemVer string of Globus Connect Server version information given by Globus Connect Server. Will be null for Globus Connect Server endpoints and collections that do not report version information and Connect Personal collections. Read only, will not be recognized on update requests.

globus_connect_setup_key

string

Key needed to complete Globus Connect Personal installation. "null" when installation setup is complete. The key can only be used once. Always "null" for Globus Connect Server entities.

guest_collection_activity_notification_policy

object

Specifies whether activity-monitoring roles on a guest collection should receive email notifications when a transfer task has completed. Defaults to null, which implies that no notifications are sent. Cannot be set on endpoints or mapped collections.

The policy object has two required members:

"transfer_use"

The usage role that the guest collection is serving in the transfer task. Expressed as an array containing one or more of the following strings: "source", "destination".

"status"

The status of the completed transfer task. Expressed as an array containing one or more of the following strings: "SUCCEEDED", "FAILED".

The policy is evaluated as a logical AND, with array values evaluated with logical OR. For example, the policy:

{
  "transfer_use": [
    "destination"
  ],
  "status": [
    "SUCCEEDED",
    "FAILED"
  ]
}

specifies that a notification will be sent only when the guest collection is the destination and the transfer task status is either a success or failure.

If either member is set to an empty array, the effect is the same as if the policy had been set to null.

Activity-monitoring roles are "administrator", "activity_manager", and "activity_monitor". Users which have a role on a guest collection by virtue of a group membership are not notified. Role inheritance from a parent endpoint or mapped collection is not applied for activity notifications.

high_assurance

boolean

This flag marks an entity as a High Assurance resource for data and API access. See High Assurance for more information.

The entity must have an authentication_timeout_mins set for this flag to be set as true. If the flag is set as true, the entity must also have a subscription at the High Assurance tier before data access and access management are allowed.

This flag cannot be updated.

restrict_transfers_to_high_assurance

string

This option restricts transfers to/from high assurance entities. The entity must have high_assurance set to "true" for this option to be set. Default value: null.

Allowed values for restrict_transfers_to_high_assurance are:

"inbound"

Only allow transfers from high assurance source collections. If the source collection is not high assurance during task submission it will result in a "PermissionDenied" error.

"outbound"

Only allow transfers to high assurance destination collections. If the destination collection is not high assurance during task submission it will result in a "PermissionDenied" error.

"all"

Only allow transfers to and from high assurance collections. If the source and destination collections are not high assurance during task submission it will result in a "PermissionDenied" error.

host_endpoint[1]

string

[DEPRECATED] Use host_endpoint_id and host_endpoint_display_name instead.

host_endpoint_display_name[1]

string

The display name for the entity referred to by host_endpoint_id if one exists and the user is allowed to view that entity.

host_endpoint_id[1]

string

For Globus Connect Server guest collections, the id of their endpoint. For Globus Connect Personal guest collections, the id of their mapped collection. Null for other entity types.

host_path

string

For Globus Connect Personal guest collections, the root path being shared on the mapped collection. Requires either the "administrator" effective role on the guest collection or the "activity_monitor" effective role on the mapped collection.

Globus Connect Server v5 guest collections and high assurance Globus Connect Personal guest collections will have this set to "/" to prevent information disclosure.

null for other entity types, or if the user does not have the correct roles.

https_server

string

If non-null, indicates that the collection has https support at the specified URL. Must be of the form https://host:port (the port is optional), with no path.

id

string

36 character unique identifier string for the entity.

in_use

boolean

"true" if any active tasks owned by the user are using the collection.

info_link

string

Link to a web page with more information about the entity. ASCII string with an http or https URL. Basic checking is done to make sure this is a valid URL, but the administrator is responsible for running a website at this URL and verifying that it’s accepting public connections.

is_globus_connect

boolean

[DEPRECATED] use entity_type instead.

keywords

string

Comma separated list of search keywords for the entity. Optional. Unicode string, max 1024 characters. Searchable.

last_accessed_time

string

Timestamp in ISO 8601 format for the last time this collection was accessed. This value is updated once daily by Globus Connect Server v5 and will be null for non Globus Connect Server v5 collections and older versions of Globus Connect Server v5.

local_user_info_available

boolean

[DEPRECATED] Not relevant for supported versions of Globus Connect Server and Personal.

location

string

"Automatic" or comma separated floats in the form "LATITUDE,LONGITUDE". "null" for guest collections.

mapped_collection_display_name

string

The display_name of mapped_collection_id if non null.

mapped_collection_id

string

For Globus Connect Server v5 guest collections, the UUID of their mapped collection. For all other entity types this will be null.

max_concurrency

integer

Can be specified only if network_use is set to "custom", otherwise will contain the preset value for the specified network_use. Will be null for guest collections.

max_parallelism

integer

Can be specified only if network_use is set to "custom", otherwise will contain the preset value for the specified network_use. Will be null for guest collections.

mfa_required

boolean

This option indicates that the entity requires multi factor authentication for user operations. The entity must have high_assurance set to true.

my_effective_roles

array of string

List of effective roles the current user has on the entity.

myproxy_dn

string

[DEPRECATED] No longer used by any supported entity types.

myproxy_server

string

[DEPRECATED] No longer used by any supported entity types.

name

string

[DEPRECATED] Use display_name instead.

network_use

string

Level of concurrency and parallelism to be used for transfer performance.

This setting is adjustable only for subscribed entities. For Globus Connect Personal mapped collections, the setting may be specified through the Globus Web App. For Globus Connect Server, the setting may be specified for an endpoint or a storage gateway through the Globus Connect Server command line interface or manager API. Settings specified on a storage gateway will be inherited by its mapped collections, overriding the settings specified on the parent endpoint.

For unsubscribed entities the "normal" level will be automatically used. This field will be null for guest collections as they inherit the network use setting for their parent mapped collections.

Allowed values for network_use are:

"normal"

The default setting. Uses an average level of concurrency and parallelism. The levels depend on the number of DTNs.

"minimal"

Uses a minimal level of concurrency and parallelism.

"aggressive"

Uses a high level of concurrency and parallelism.

"custom"

Uses custom values of concurrency and parallelism set by the entity admin. When setting this level, you must also set the max_concurrency, preferred_concurrency,max_parallelism, and preferred_parallelism options.

non_functional

boolean

[DEPRECATED] use entity_type instead to determine if an entity is an endpoint.

non_functional_endpoint_display_name

string

The display_name of the Globus Connect Server v5 endpoint if non_functional_endpoint_id is non null.

non_functional_endpoint_id

string

For Globus Connect Server v5 mapped and guest collections, the UUID of their host endpoint. For all other entity types this will be null.

oauth_server

string

[DEPRECATED] No longer used by any supported entity types.

organization

string

Organization that runs the entity. Unicode string, max 1024 characters, no new lines. Searchable.

owner_id

string

Identity id of the entity owner/creator. Defaults to your effective_id when created. Can be overridden at creation time to one of your linked identities. Cannot be changed after creation time.

owner_string

string

Identity name of an entity administrator. During creation, it will be set to the name of owner_id. After creation, it can be changed to any administrator that is set by a user-identity role (and that role may not be deleted). For security, the new administrator must perform the update. Searchable.

preferred_concurrency

integer

Can be specified only if network_use is set to "custom", otherwise will contain the preset value for the specified network_use. Will be null for guest collections.

preferred_parallelism

integer

Can be specified only if network_use is set to "custom", otherwise will contain the preset value for the specified network_use. Will be null for guest collections.

public

boolean

True if the entity definition should be visible to Globus users who don’t have an effective role on it.

requester_pays

boolean

Only can be true for Globus Connect Server v5 collections, and cannot be set through the Transfer API. Reflects storage policy options such as s3_requester_pays in the S3 Storage Policies Document that indicate costs of using the underlying storage system will be charged to the account of the registered credentials. Note that this is not necessarily the account of the user making Transfer API requests.

s3_owner_activated

boolean

[DEPRECATED] Always "false".

s3_url

null

[DEPRECATED] Always null.

shareable

boolean

[DEPRECATED] use entity_type instead.

sharing_target_endpoint[1]

string

[DEPRECATED] use host_endpoint_id and host_endpoint_display_name instead.

sharing_target_root_path

string

[DEPRECATED] use host_path instead.

skip_auto_delete

boolean

Specifies whether a Globus Connect Server guest collection is exempt from its parent mapped collection auto_delete_timeout policy. Will be null for all other entity types.

storage_type

string

[DEPRECATED] Unused.

subscription_id

string

If the entity is subscribed this will be a UUID string for its subscription, otherwise it will be null.

This value can only be set on Globus Connect Personal mapped collections using the Transfer API. Globus Connect Server v5 endpoints use the Globus Connect Server Manager API to set their subscription_id. Child entities inherit the field from their parents.

If you only have access to one subscription id, you can PUT with the special string "DEFAULT" to use that subscription id.

subscription_admin_verified

boolean

A flag that can be set to true to indicate to users that the collection is operated and maintained by the subscribing organization. The collection must be subscribed and can only be set to true by an administrator of the subscription. Child entities do not inherit this field.

For Globus Connect Personal collections this field is managed through the Transfer API. Collection administrators can update this field with the Update Globus Connect Personal collection by id resource. Subscription administrators can update this field on collections associated with their subscription using the Set Subscription Admin Verified resource.

For Globus Connect Server collections this field is managed through the Globus Connect Server Manager API.

tlsftp_server

string

For Globus Connect Server v5 collections, the url for the tlsftp server used for data access. Will be in the form of "tlsftp://{collection_domain}:{port}". null for other entity types.

user_message

string

A message for clients to display to users when interacting with this entity, max length 256 characters. This value can only be set on endpoints and Globus Connect Personal mapped collections, but will be inherited by child collections under them.

user_message_link

string

Link to additional messaging for clients to display to users when interacting with this entity. ASCII string with an http or https URL. Basic checking is done to make sure this is a valid URL, but the administrator is responsible for running a website at this URL and verifying that it’s accepting public connections. This value can only be set on endpoints and Globus Connect Personal mapped collections, but will be inherited by child collections under them.

username

string

[DEPRECATED] Use owner_id and owner_string instead.
Note

Some fields have defaults for endpoints and Globus Connect Personal mapped collections, but their defaults for child collections depend on the settings of the parent. These fields are as follows:

Field Name Default behavior

force_verify

false for endpoints and Globus Connect Personal mapped collections, but inherits from the host for child collections.

disable_verify

false for endpoints and Globus Connect Personal mapped collections, but inherits from the host for child collections.

2.2. Server Document

The server document contains data about gridftp network connections. These values are read-only in the Transfer API for all entity types.

Server Document Example
{
  "DATA_TYPE": "server",
  "hostname": "b7a4f1.75bc.data.globus.org",
  "id": 718086,
  "incoming_data_port_end": null,
  "incoming_data_port_start": null,
  "is_connected": true,
  "is_paused": false,
  "outgoing_data_port_end": null,
  "outgoing_data_port_start": null,
  "port": 2811,
  "scheme": "gsiftp",
  "subject": null,
  "uri": "gsiftp://b7a4f1.75bc.data.globus.org:2811"
}

2.2.1. Server Fields

Field Name JSON Type Description

DATA_TYPE

string

Always has value "server" to indicate this document type.

id

int

Unique identifier for a server.

hostname

string

Hostname of the server.

port

int

Port the gridftp server is listening on. Default: 2811.

scheme

string

URI scheme (protocol) used by the server. Must be "gsiftp" or "ftp". Default: "gsiftp".

subject

string

[DEPRECATED] subject of the x509 certificate of the gridftp server. Only used internally for Globus Connect Personal collections.

incoming_data_port_start

int

Start (inclusive) of port range allowed for incoming GridFTP data connections. The purpose of this field is to indicate to firewall administrators at other sites how to allow traffic between this server and their own servers. If "null", indicates that an administrator has not specified the configuration (the allowed range is unknown). A range of 1024-65535 indicates a completely open configuration. Will be a subset of 1024-65535.

incoming_data_port_end

int

End (inclusive) of port range allowed for incoming data connections. Must be greater or equal to incoming_data_port_range_start.

outgoing_data_port_start

int

Like incoming_data_port_start but for outgoing data connections.

outgoing_data_port_end

int

Like incoming_data_port_end but for outgoing data connections.

uri

string

[DEPRECATED] URI of the server. This is a derived field combining the scheme, hostname, and port.

is_connected

boolean

[DEPRECATED] Use gcp_connected in the collection document instead.

is_paused

boolean

[DEPRECATED] Use gcp_paused in the collection document instead.

3. Path Arguments

Name Type Description

endpoint_or_collection_id

string

The id field of the endpoint or collection.

collection_id

string

The id field of the collection.

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

5. Common Errors

The error code can be found in the HTTP response body JSON document. See error overview .

Code HTTP Status Description

EndpointNotFound[1]

404

If <endpoint_or_collection_id> not found.

PermissionDenied

403

If user does not have privileges to get, modify, or delete the specified entity.

EndpointDeleted[1]

409

See Get endpoint or collection by id. The error document contains a deleted_time field indicating when the endpoint or collection was deleted, in addition to the standard error fields.

ClientError.Conflict

409

If a role assignment with the same principal and role already exists.

ServiceUnavailable

503

If the service is down for maintenance.

6. Operations

6.1. Get endpoint or collection by id

Get a single endpoint or collection by id. All fields are included by default, including the server subdocuments, but the fields query parameter can be used to fetch only specific fields. Use "server" in the fields list to include server subdocuments in a limited field list.

Note
Returns an "EndpointDeleted" error instead of "EndpointNotFound" for deleted endpoints and collections.
Authorization

Requires that the endpoint or collection is public or that the user has an "administrator" "restricted_administrator" or "activity_monitor" effective role on the endpoint or collection.

URL

/endpoint/<endpoint_or_collection_id>[1]

Method

GET

Response Body

Endpoint or Collection document

6.2. Get my effective collection pause rules

Get all pause rules on a collection that affect the current user. Sensitive fields that are visible only to an "activity_monitor" will be removed for regular users.

See also: pause_rule_limited document.

Authorization

Requires that the endpoint is public or that the user has an "administrator" or "restricted_administrator" effective role on the endpoint or collection.

URL

/endpoint/<collection_id>/my_effective_pause_rule_list[1]

Method

GET

Response Body

List of "pause_rule_limited" documents

6.3. Get endpoint or collection server list

Get a list of all servers belonging to the specified endpoint or collection. Note that this is the same as the server list included under the "DATA" key of the endpoint or collection document.

Authorization

Requires that the endpoint or collection is public or that the user has an "administrator", "restricted_administrator", or "activity_monitor" effective role on the endpoint or collection.

URL

/endpoint/<endpoint_or_collection_id>/server_list[1]

Method

GET

Response Body

List of server documents

6.4. Get server by id

Get a specific server belonging to the specified endpoint or collection.

Authorization

Requires that the endpoint or collection is public or that the user has an "administrator", "restricted_administrator", or "activity_monitor" effective role on the endpoint or collection.

URL

/endpoint/<endpoint_or_collection_id>/server/<server_id>[1]

Method

GET

Response Body

A "server" document

6.5. Get my guest collection list

Get a list of guest collections for which the user has an "administrator", or "access_manager" effective role. hosted by a given endpoint or mapped collection.

Returns a "BadRequest" error if called on a guest collection.

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

Authorization

Same as get endpoint or collection by ID

URL

/endpoint/<endpoint_or_collection_id>/my_shared_endpoint_list[1]

Method

GET

Response Body

An "endpoint_list"[1] document.

6.5.1. Query Parameters

Query Parameter Type Default Description

limit

int

1000

Maximum number of results to return. 1000 is both the default and maximum.

offset

int

0

Return results starting from this offset within the total result set.

6.6. Get guest collection list

Get all guest collections hosted by a specific endpoint or Globus Connect Personal mapped collection. This resource currently does not support listing guest collections for a specified Globus Connect Server mapped collection.

Currently, only the guest collection id attribute is returned.

This resource uses next token paging. By default, the limit is 1000 results per API call. The query parameter max_results can override this; it must be >= 1 and <= 1000.

Authorization

Same as get endpoint or collection by ID

URL

/endpoint/<endpoint_or_collection_id>/shared_endpoint_list?[next_token=TOKEN][max_results=MAX_RESULTS][1]

Method

GET

Response Body

 
{
  "next_token": <null or string>
  "shared_endpoints": [
    {
      "id": <string>
    },
    ...
  ]
}
1. This use of the term "endpoint" is a case of legacy endpoint terminology and can also/exclusively refer to collections