Domains

The Domains API describes the routes and data types used by the GCS Manager to provide support for custom domain and certificates for use with the GCS Manager and its collections.

Domains Overview

Method	API Path	Description
`PUT`	/api/collections/{collection_id}/domain	Set custom domain for a collection
`DELETE`	/api/collections/{collection_id}/domain	Delete custom domain for a collection
`GET`	/api/collections/{collection_id}/domain	Get custom domain for a collection
`PUT`	/api/endpoint/domain	Set endpoint domain
`DELETE`	/api/endpoint/domain	Delete endpoint domain
`GET`	/api/endpoint/domain	Get endpoint domain

Details

Set custom domain for a collection

PUT /api/collections/{collection_id}/domain

The domain is used for the collection. If this is a mapped collection and the wildcard property is set to true, then all all guest collections associated with this collection that do not have a custom domain will be updated to use subdomains of that domain. Otherwise, only this collection will use that domain.

This requires an administrator role on the Endpoint

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Path parameters

▷ collection_id

Id of the collection

Parameter	Type	Description
collection_id (required)	string <uuid>	Id of the collection

Request body

Content-Type: application/json

Custom domain description

Name	Type	Description
DATA_TYPE	string `domain#1.0.0`	Type of this document
certificate	string `^(.* )?-----BEGIN CERTIFICATE-----.*`	PEM-Encoded X.509 certificate for this domain
certificate_chain	string `^(.* )?-----BEGIN CERTIFICATE-----.*`	PEM-Encoded X.509 certificate chain for this domain. Only needed if there are intermediate certificates that must also be sent to clients to allow them to verify the certificate. [Private]
certificate_chain_path	string `^/.*`	Path to a file containing the X.509 certificate chain for this domain. This file path must contain a sequence of valid certificate and be present on each data transfer node. [Private]
certificate_path	string `^/.*`	Path to a file containing the X.509 certificate for this domain. This file path must contain a valid certificate and be present on each data transfer node. [Private]
domain_name	string `^((?!-)[A-Za-z0-9-]{1,63}(?`	Domain name
private_key	string `^(.* )?-----BEGIN PRIVATE KEY-----.*`	PEM-Encoded private key for the certificate[Private]
private_key_path	string `^/.*`	Path to a file containing the private key for this domain. This file path must contain a valid key and be present on each data transfer node. [Private]
wildcard	boolean	Flag indicating whether this is a wildcard domain or not. When setting a custom domain for a mapped collection, the domain may optionally be a wildcard domain. If it is a wildcard domain, the guest collections will be created as subdomains of the mapped collection domain; if not, guest collections will be created as subdomains of the endpoint domain.

Example

{
  "DATA_TYPE": "domain#1.0.0",
  "certificate": "string",
  "certificate_chain": "string",
  "certificate_chain_path": "string",
  "certificate_path": "string",
  "domain_name": "string",
  "private_key": "string",
  "private_key_path": "string",
  "wildcard": true
}

Responses

200 - Set collection domain 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"
}

404 - Not found

415 - Unsupported media type

422 - Unprocessable entity

Delete custom domain for a collection

DELETE /api/collections/{collection_id}/domain

Delete the custom collection domain.

If this is a mapped collection, this will cause the collection to revert to a subdomain of the endpoint’s domain (if it is wildcard domain) or a subdomain of the endpoint’s data.globus.org domain. If this mapped collection has a wildcard domain when this is called, then all guest collections without custom domains will have their domains changed as well.

If this is a guest collection, and the mapped collection it was created from has a custom wildcard domain, then this collection will become a subdomain of that domain; otherwise it will revert to a subdomain of either the endpoint’s domain (if it is a wildcard domain) or a subdomain of the endpoint’s data.globus.org domain.

This requires an administrator role on the Endpoint.

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Path parameters

▷ collection_id

Id of the collection

Parameter	Type	Description
collection_id (required)	string <uuid>	Id of the collection

Responses

200 - Delete collection domain 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"
}

404 - Not found

Get custom domain for a collection

GET /api/collections/{collection_id}/domain

Get the custom domain document associated with this collection.

This requires an administrator role on the Endpoint

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Path parameters

▷ collection_id

Id of the collection

Parameter	Type	Description
collection_id (required)	string <uuid>	Id of the collection

Responses

200 - Get collection domain 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 ( Domain )
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": "domain#1.0.0",
      "certificate": "string",
      "certificate_chain": "string",
      "certificate_chain_path": "string",
      "certificate_path": "string",
      "domain_name": "string",
      "private_key": "string",
      "private_key_path": "string",
      "wildcard": true
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "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"
}

404 - Not found

Details

Set endpoint domain

PUT /api/endpoint/domain

The domain is used for the endpoint itself. If the wildcard property is set to true, then all all collections associated with that endpoint that do not have a custom domain will be updated to use subdomains of that domain. Otherwise, only the endpoint will use that domain.

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Request body

Content-Type: application/json

Custom domain description

Name	Type	Description
DATA_TYPE	string `domain#1.0.0`	Type of this document
certificate	string `^(.* )?-----BEGIN CERTIFICATE-----.*`	PEM-Encoded X.509 certificate for this domain
certificate_chain	string `^(.* )?-----BEGIN CERTIFICATE-----.*`	PEM-Encoded X.509 certificate chain for this domain. Only needed if there are intermediate certificates that must also be sent to clients to allow them to verify the certificate. [Private]
certificate_chain_path	string `^/.*`	Path to a file containing the X.509 certificate chain for this domain. This file path must contain a sequence of valid certificate and be present on each data transfer node. [Private]
certificate_path	string `^/.*`	Path to a file containing the X.509 certificate for this domain. This file path must contain a valid certificate and be present on each data transfer node. [Private]
domain_name	string `^((?!-)[A-Za-z0-9-]{1,63}(?`	Domain name
private_key	string `^(.* )?-----BEGIN PRIVATE KEY-----.*`	PEM-Encoded private key for the certificate[Private]
private_key_path	string `^/.*`	Path to a file containing the private key for this domain. This file path must contain a valid key and be present on each data transfer node. [Private]
wildcard	boolean	Flag indicating whether this is a wildcard domain or not. When setting a custom domain for a mapped collection, the domain may optionally be a wildcard domain. If it is a wildcard domain, the guest collections will be created as subdomains of the mapped collection domain; if not, guest collections will be created as subdomains of the endpoint domain.

Example

{
  "DATA_TYPE": "domain#1.0.0",
  "certificate": "string",
  "certificate_chain": "string",
  "certificate_chain_path": "string",
  "certificate_path": "string",
  "domain_name": "string",
  "private_key": "string",
  "private_key_path": "string",
  "wildcard": true
}

Responses

200 - Set endpoint domain 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

Delete endpoint domain

DELETE /api/endpoint/domain

Delete the custom endpoint domain. This will cause the endpoint to revert to using a data.globus.org domain for the GCS Manager and any collections which do not have custom domains associated with them.

This requires an administrator role on the Endpoint.

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Responses

200 - Delete endpoint domain 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"
}

Get endpoint domain

GET /api/endpoint/domain

Get the custom domain document associated with this endpoint.

This requires an administrator role on the Endpoint.

Authorization

RoleAuthorizer:
- endpoint:owner
- endpoint:administrator

Responses

200 - Get endpoint domain 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"
}