Domains

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

Register a new custom domain and certificate to to be used to serve this collection.

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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "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

Register a new custom domain and certificate to to be used to serve the endpoint or collection.

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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "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.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

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