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.

Endpoint Overview

Method	API Path	Description
`PUT`	/api/endpoint/subscription_id	Set the endpoint subscription id
`PUT`	/api/endpoint/owner_string	Set endpoint owner string
`DELETE`	/api/endpoint/owner_string	Reset advertised owner string
`PUT`	/api/endpoint/owner	Set endpoint owner
`GET`	/api/endpoint	Get endpoint definition
`PATCH`	/api/endpoint	Update an endpoint
`PUT`	/api/endpoint	Update an endpoint

Details

Set the endpoint subscription id

PUT /api/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 caller 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 or remove the subscription_id from the endpoint if it is one that they managed.
Caller has a role and is a subscription manager: Set the subscription_id to a subcription they manage on an endpoint even if it is currently managed by a subscription that the caller is not a manager of.

Authorization

SubscriptionManagerAuthorizer
RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Request body

Table 1. Content-Type: application/json
Name	Type	Description
DATA_TYPE	string `endpoint_subscription#1.0.0`	Type of this document
subscription_id	string	Either the id 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": "string"
}

Responses

200 - Set endpoint owner response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string	String response code
data	array of object
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

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

400 - Bad Request

401 - Unauthorized

415 - Unsupported media type

422 - Unprocessable entity

Details

Set endpoint owner string

PUT /api/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

Content-Type: application/json

Owner string document

Name	Type	Description
DATA_TYPE	string `owner_string#1.0.0`	Type of this document
identity_id	string <uuid>	Globus Auth Identity id

Example

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

Responses

200 - Set endpoint owner string response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string	String response code
data	array of object
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

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

400 - Bad Request

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `permission_denied`
http_response_code	any type `403`
detail	string or MissingRequiredRole
DATA_TYPE	string `result#1.0.0`	Type of this document
data	array of 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.
message	string	Message describing this result

{
  "code": "permission_denied",
  "http_response_code": 403,
  "detail": "string",
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

415 - Unsupported media type

422 - Unprocessable entity

Reset advertised owner string

DELETE /api/endpoint/owner_string

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

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Responses

200 - Reset advertised owner string response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string	String response code
data	array of object
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

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

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `permission_denied`
http_response_code	any type `403`
detail	string or MissingRequiredRole
DATA_TYPE	string `result#1.0.0`	Type of this document
data	array of 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.
message	string	Message describing this result

{
  "code": "permission_denied",
  "http_response_code": 403,
  "detail": "string",
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

Details

Set endpoint owner

PUT /api/endpoint/owner

Assign a new identity to act as the endpoint owner.

Authorization

RoleAuthorizer:
- endpoint:owner

Request body

Content-Type: application/json

Schema for processing the endpoint_owner#1.0.0 data type

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 - Set endpoint owner response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
DATA_TYPE	string `result#1.0.0`	Type of this document
code	string	String response code
data	array of object
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

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

400 - Bad Request

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `permission_denied`
http_response_code	any type `403`
detail	string or MissingRequiredRole
DATA_TYPE	string `result#1.0.0`	Type of this document
data	array of 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.
message	string	Message describing this result

{
  "code": "permission_denied",
  "http_response_code": 403,
  "detail": "string",
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

415 - Unsupported media type

422 - Unprocessable entity

Details

Get endpoint definition

GET /api/endpoint

Get the endpoint.

Authorization

PublicAuthorizer
RoleAuthorizer:
- endpoint:owner
- endpoint:administrator
- endpoint:activity_manager
- endpoint:activity_monitor
- collection:administrator:*
- collection:activity_manager:*
- collection:activity_monitor:*
- collection:access_manager:*
StorageGatewayAuthorizer
- *

Responses

200 - Get endpoint response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `success`
data	array ( Endpoint )
DATA_TYPE	string `result#1.0.0`	Type of this document
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

{
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "endpoint#1.0.0",
      "allow_udt": true,
      "contact_email": "string",
      "contact_info": "string",
      "department": "string",
      "description": "string",
      "display_name": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "gcs_manager_url": "string",
      "info_link": "string",
      "keywords": [
        "string"
      ],
      "max_concurrency": 1,
      "max_parallelism": 1,
      "network_use": "normal",
      "organization": "string",
      "preferred_concurrency": 1,
      "preferred_parallelism": 1,
      "public": true,
      "subscription_id": "string"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

401 - Unauthorized

Update an endpoint

PATCH /api/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 of string `endpoint`	List of document types to include in the response

Request body

Content-Type: 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.

Version 1.1.0 of the endpoint includes support for customizing the TCP port that the GridFTP listens on.

One of the following schemas:

Example

{
  "DATA_TYPE": "endpoint#1.0.0",
  "allow_udt": true,
  "contact_email": "string",
  "contact_info": "string",
  "department": "string",
  "description": "string",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "gcs_manager_url": "string",
  "info_link": "string",
  "keywords": [
    "string"
  ],
  "max_concurrency": 1,
  "max_parallelism": 1,
  "network_use": "normal",
  "organization": "string",
  "preferred_concurrency": 1,
  "preferred_parallelism": 1,
  "public": true,
  "subscription_id": "string"
}

Responses

200 - Update endpoint response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `success`
data	array ( Endpoint )
DATA_TYPE	string `result#1.0.0`	Type of this document
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

{
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "endpoint#1.0.0",
      "allow_udt": true,
      "contact_email": "string",
      "contact_info": "string",
      "department": "string",
      "description": "string",
      "display_name": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "gcs_manager_url": "string",
      "info_link": "string",
      "keywords": [
        "string"
      ],
      "max_concurrency": 1,
      "max_parallelism": 1,
      "network_use": "normal",
      "organization": "string",
      "preferred_concurrency": 1,
      "preferred_parallelism": 1,
      "public": true,
      "subscription_id": "string"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

400 - Bad Request

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `permission_denied`
http_response_code	any type `403`
detail	string or MissingRequiredRole
DATA_TYPE	string `result#1.0.0`	Type of this document
data	array of 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.
message	string	Message describing this result

{
  "code": "permission_denied",
  "http_response_code": 403,
  "detail": "string",
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

415 - Unsupported media type

422 - Unprocessable entity

Update an endpoint

PUT /api/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 of string `endpoint`	List of document types to include in the response

Request body

Content-Type: application/json

Version 1.1.0 of the endpoint includes support for customizing the TCP port that the GridFTP listens on.

One of the following schemas:

Example

{
  "DATA_TYPE": "endpoint#1.0.0",
  "allow_udt": true,
  "contact_email": "string",
  "contact_info": "string",
  "department": "string",
  "description": "string",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "gcs_manager_url": "string",
  "info_link": "string",
  "keywords": [
    "string"
  ],
  "max_concurrency": 1,
  "max_parallelism": 1,
  "network_use": "normal",
  "organization": "string",
  "preferred_concurrency": 1,
  "preferred_parallelism": 1,
  "public": true,
  "subscription_id": "string"
}

Responses

200 - Update endpoint response

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `success`
data	array ( Endpoint )
DATA_TYPE	string `result#1.0.0`	Type of this document
detail	any type
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.
http_response_code	integer	Numeric HTTP response code
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.
message	string	Message describing this result

{
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "endpoint#1.0.0",
      "allow_udt": true,
      "contact_email": "string",
      "contact_info": "string",
      "department": "string",
      "description": "string",
      "display_name": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "gcs_manager_url": "string",
      "info_link": "string",
      "keywords": [
        "string"
      ],
      "max_concurrency": 1,
      "max_parallelism": 1,
      "network_use": "normal",
      "organization": "string",
      "preferred_concurrency": 1,
      "preferred_parallelism": 1,
      "public": true,
      "subscription_id": "string"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}

400 - Bad Request

401 - Unauthorized

403 - Permission denied

Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Name	Type	Description
code	string `permission_denied`
http_response_code	any type `403`
detail	string or MissingRequiredRole
DATA_TYPE	string `result#1.0.0`	Type of this document
data	array of 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.
message	string	Message describing this result

{
  "code": "permission_denied",
  "http_response_code": 403,
  "detail": "string",
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}