Endpoint

A GCS Endpoint is an entity that represents an access point to data storage. In GCSv5, this includes the following types of items:

One or more Storage Gateways which define policies to access specific data storage rooted in some sort of file system or object store. In this version of the specification, ActiveScale, Azure Blob Storage, BlackPearl, Box, Ceph, Google Drive, Google Cloud Storage, HPSS, iRODS, OneDrive, POSIX, and S3 Storage Gateways are supported.
One or more Collections, which may define either a set of data on a Storage Gateway that is shared with other Globus users or publicly, or a set of data on a Storage Gateway that Globus users access with their own local or cloud accounts.
One or more nodes which define physical servers providing access to the GCS endpoint resources.

Overview

Method	API Path	Description
`GET`	/endpoint	Get Endpoint
`PATCH`	/endpoint	Update Endpoint
`PUT`	/endpoint	Update Endpoint

Overview

Method	API Path	Description
`PUT`	/endpoint/owner	Update the endpoint owner

Overview

Method	API Path	Description
`PUT`	/endpoint/subscription_id	Update the endpoint subscription

Overview

Method	API Path	Description
`PUT`	/endpoint/owner_string	Put endpoint owner string
`DELETE`	/endpoint/owner_string	Delete role-based endpoint advertised owner string

Details

Get Endpoint

GET /endpoint

Get the Globus Connect Server’s Endpoint document.

Authorization

PublicAuthorizer
RoleAuthorizer: [ endpoint:owner, endpoint:administrator, endpoint:activity_manager, endpoint:activity_monitor, collection:administrator:*, collection:activity_manager:*, collection:activity_monitor:*, collection:access_manager:* ]
CollectionACLAuthorizer: [ * ]
StorageGatewayAuthorizer [ * ]

Responses

200 - Get Endpoint Response

Table 1. application/json
Name	Type	Description
code	`success`
data	array (object) ( Endpoint )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "endpoint#1.0.0",
      "public": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "display_name": "string",
      "gcs_manager_url": "https://gcs.data.globus.org/",
      "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
      "network_use": "normal",
      "max_concurrency": 1,
      "preferred_concurrency": 1,
      "max_parallelism": 1,
      "preferred_parallelism": 1,
      "organization": "string",
      "department": "string",
      "keywords": [
        "string"
      ],
      "description": "string",
      "contact_email": "user@example.com",
      "contact_info": "string",
      "info_link": "http://example.com",
      "allow_udt": false
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

Update Endpoint

PATCH /endpoint

Update the Endpoint document, changing only the properties included in the input. Items explicitly set to null in the input are removed from the Endpoint document. This operation optionally returns the Endpoint after applying the changes in the input if the include=endpoint query parameter is passed to this operation.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Query Parameters

Parameter	Type	Description
include	array(string) `endpoint`	List of document types to include in the response.

Request body

application/json

A Globus Connect Server endpoint is a deployment of Globus Connect Server version 5. A single endpoint may optionally include multiple data transfer nodes. The endpoint provides a link between a Globus Connect Server deployment and the Globus Transfer service. The endpoint describes services for accessing data via GridFTP and HTTPS and also for configuring and managing the policies associated with that access.

Name	Type	Description
DATA_TYPE	string `endpoint#1.0.0`	Type of this document
public	boolean	Flag indicating whether this endpoint is visible to all other Globus users. If false, only users which have been granted a role on the endpoint or one of its collections, or belong to a domain allowed access to any of its storage gateways may view it.
display_name	string	Friendly name for the endpoint, not unique. Unicode string, no new lines (`\r` or `\n`). Searchable.
subscription_id	string anyOf { <uuid>, `DEFAULT` }	The UUID of the subscription that is managing this endpoint. This may be the special value `DEFAULT` when using this as input to PATCH or PUT to use the caller’s default subscription id.
network_use	string `normal`, `minimal`, `aggressive`, `custom`	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 physical servers in the endpoint. 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 endpoint admin. When setting this level, you must also set the max_concurrency, preferred_concurrency, max_parallelism, and preferred_parallelism options.
max_concurrency	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
preferred_concurrency	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
max_parallelism	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
preferred_parallelism	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
organization	string	Organization that runs the server(s) represented by the endpoint. Optional to preserve backward compatibility, but will eventually be required and all clients are encouraged to require users to specify it. Unicode string, max 1024 characters, no new lines.
department	string	Department within organization that runs the server(s). Searchable. Optional. Unicode string, max 1024 characters, no new lines.
keywords	array (string)	List of search keywords for the endpoint. Optional. Unicode string, max 1024 characters total across all strings.
description	string	A description of the endpoint.
contact_email	string <email>	Email address of the support contact for the server(s) represented by the endpoint.
contact_info	string	Other non-email contact information for the endpoint, e.g. phone and mailing address.
info_link	string <uri>	Link to a web page with more information about the endpoint. The administrator is responsible for running a website at this URL and verifying that it is accepting public connections.
allow_udt	boolean	Allow data transfer on this endpoint using the UDT protocol.

Example

{
  "DATA_TYPE": "endpoint#1.0.0",
  "public": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "display_name": "string",
  "gcs_manager_url": "https://gcs.data.globus.org/",
  "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
  "network_use": "normal",
  "max_concurrency": 1,
  "preferred_concurrency": 1,
  "max_parallelism": 1,
  "preferred_parallelism": 1,
  "organization": "string",
  "department": "string",
  "keywords": [
    "string"
  ],
  "description": "string",
  "contact_email": "user@example.com",
  "contact_info": "string",
  "info_link": "http://example.com",
  "allow_udt": false
}

Responses

200 - Update Endpoint Response.

Table 2. application/json
Name	Type	Description
code	string `success`
data	array (object) ( Endpoint )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "endpoint#1.0.0",
      "public": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "display_name": "string",
      "gcs_manager_url": "https://gcs.data.globus.org/",
      "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
      "network_use": "normal",
      "max_concurrency": 1,
      "preferred_concurrency": 1,
      "max_parallelism": 1,
      "preferred_parallelism": 1,
      "organization": "string",
      "department": "string",
      "keywords": [
        "string"
      ],
      "description": "string",
      "contact_email": "user@example.com",
      "contact_info": "string",
      "info_link": "http://example.com",
      "allow_udt": false
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

400 - Bad request

401 - Unauthorized

403 - Missing required role

415 - UnsupportedMedia

422 - UnprocessableEntity

Update Endpoint

PUT /endpoint

Update the Endpoint document, replacing all properties with those in the input. This operation optionally returns the Endpoint after the update if the include=endpoint query parameter is passed to this operation.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Query Parameters

Parameter	Type	Description
include	array(string) `endpoint`	List of document types to include in the response.

Request body

application/json

Name	Type	Description
DATA_TYPE	string `endpoint#1.0.0`	Type of this document
public	boolean	Flag indicating whether this endpoint is visible to all other Globus users. If false, only users which have been granted a role on the endpoint or one of its collections, or belong to a domain allowed access to any of its storage gateways may view it.
display_name	string	Friendly name for the endpoint, not unique. Unicode string, no new lines (`\r` or `\n`). Searchable.
subscription_id	string anyOf { <uuid>, `DEFAULT` }	The UUID of the subscription that is managing this endpoint. This may be the special value `DEFAULT` when using this as input to PATCH or PUT to use the caller’s default subscription id.
network_use	string `normal`, `minimal`, `aggressive`, `custom`	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 physical servers in the endpoint. 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 endpoint admin. When setting this level, you must also set the max_concurrency, preferred_concurrency, max_parallelism, and preferred_parallelism options.
max_concurrency	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
preferred_concurrency	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
max_parallelism	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
preferred_parallelism	integer	Admin-specified value when the network_use property’s value is `custom`; otherwise the preset value for the specified network_use.
organization	string	Organization that runs the server(s) represented by the endpoint. Optional to preserve backward compatibility, but will eventually be required and all clients are encouraged to require users to specify it. Unicode string, max 1024 characters, no new lines.
department	string	Department within organization that runs the server(s). Searchable. Optional. Unicode string, max 1024 characters, no new lines.
keywords	array (string)	List of search keywords for the endpoint. Optional. Unicode string, max 1024 characters total across all strings.
description	string	A description of the endpoint.
contact_email	string <email>	Email address of the support contact for the server(s) represented by the endpoint.
contact_info	string	Other non-email contact information for the endpoint, e.g. phone and mailing address.
info_link	string <uri>	Link to a web page with more information about the endpoint. The administrator is responsible for running a website at this URL and verifying that it is accepting public connections.
allow_udt	boolean	Allow data transfer on this endpoint using the UDT protocol.

Example

{
  "DATA_TYPE": "endpoint#1.0.0",
  "public": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "display_name": "string",
  "gcs_manager_url": "https://gcs.data.globus.org/",
  "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
  "network_use": "normal",
  "max_concurrency": 1,
  "preferred_concurrency": 1,
  "max_parallelism": 1,
  "preferred_parallelism": 1,
  "organization": "string",
  "department": "string",
  "keywords": [
    "string"
  ],
  "description": "string",
  "contact_email": "user@example.com",
  "contact_info": "string",
  "info_link": "http://example.com",
  "allow_udt": false
}

Responses

200 - Endpoint Update Response

Table 3. application/json
Name	Type	Description
code	string `success`
data	array (object) ( Endpoint )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "endpoint#1.0.0",
      "public": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "display_name": "string",
      "gcs_manager_url": "https://gcs.data.globus.org/",
      "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896",
      "network_use": "normal",
      "max_concurrency": 1,
      "preferred_concurrency": 1,
      "max_parallelism": 1,
      "preferred_parallelism": 1,
      "organization": "string",
      "department": "string",
      "keywords": [
        "string"
      ],
      "description": "string",
      "contact_email": "user@example.com",
      "contact_info": "string",
      "info_link": "http://example.com",
      "allow_udt": false
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

400 - Bad request

401 - Unauthorized

403 - Missing required role

415 - UnsupportedMedia

422 - UnprocessableEntity

Details

Update the endpoint owner

PUT /endpoint/owner

Assign a new identity to act as the endpoint owner.

Authorization

RoleAuthorizer: [ endpoint:owner ]

Request body

application/json

Owner document.

Name	Type	Description
DATA_TYPE	string `endpoint_owner#1.0.0`	Type of this document
identity_id	string <uuid>	Auth identity ID of the endpoint owner

Example

{
  "DATA_TYPE": "endpoint_owner#1.0.0",
  "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1"
}

Responses

200 - Owner update Response

Table 4. application/json
Name	Type	Description
code	string `success`
data	array (object)
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {}
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

400 - Bad request

401 - Unauthorized

403 - Missing required role

415 - UnsupportedMedia

422 - UnprocessableEntity

Details

Update the endpoint subscription

PUT /endpoint/subscription_id

Change the subscription_id of this endpoint. Because subscription is enforcement is handled in a separate service than GCS and an organization’s subscription manager may not be the administrator of the endpoint, this API has allows for both role-based authorization and subscription manager based authorization.

The authorization allows the following:

Caller has a role but is not subscription manager: Remove an existing subscription from an endpoint, even if the callers is not a manager for that subscription.
Caller does not have a role but is a subscription manager: Set the subscription_id to a subscription they manage on a currently-unmanaged endpoint.
Caller has a role and is a subscription manager: Set the subscription_id to a subscription they manage on an endpoint even if it is currently managed by a subscription that the caller is not a manager of.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]
SubscriptionManagerAuthorizer

Request body

application/json

Endpoint subscription request document

Name	Type	Description
DATA_TYPE	string `endpoint_subscription#1.0.0`	Type of this document
subscription_id	One of { string <uuid>, string `DEFAULT` }	Either the UUID of a Globus subscription or the special value "DEFAULT" if the caller has only one subscription associated with their identity set.

Example

{
  "DATA_TYPE": "endpoint_subscription#1.0.0",
  "subscription_id": "2d99530d-3b20-44cb-94d3-61d8f85cd896"
}

Responses

200 - Owner update Response

Table 5. application/json
Name	Type	Description
code	string `success`
data	array (object)
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {}
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

Details

Put endpoint owner string

PUT /endpoint/owner_string

Modify the endpoint’s advertised owner to match the username of one of the caller’s linked identities. The identity must have an administrator role on the endpoint.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Request body

application/json

Owner string document.

Name	Type	Description
DATA_TYPE	string `owner_string#1.0.0`	Type of this document
identity_id	string <uuid>	Auth identity username

Example

{
  "DATA_TYPE": "owner_string#1.0.0",
  "identity_id": "2574c430-0c01-4695-92fa-4bad3c21f6ab"
}

Responses

200 - Set endpoint owner string response

Table 6. application/json
Name	Type	Description
code	string `success`
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
data	array (object)
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}

Delete role-based endpoint advertised owner string

DELETE /endpoint/owner_string

Reset the endpoint’s advertised owner to the client_id of the endpoint.

Authorization

RoleAuthorizer: [ endpoint:administrator, endpoint:owner ]

Responses

200 - Reset endpoint owner string response

Table 7. application/json
Name	Type	Description
code	string `success`
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
data	array (object)
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}