Domains

This section describes the routes and data types to the GCS Manager API to provide support for custom domain and certificates for use with the GCS Manager and its collections.

Overview

Method	API Path	Description
`GET`	/endpoint/domain	Get Endpoint Domain
`PUT`	/endpoint/domain	Put Endpoint Domain
`DELETE`	/endpoint/domain	Delete Endpoint Domain

Overview

Method	API Path	Description
`GET`	/collections/{collection_id}/domain	Get collection domain
`PUT`	/collections/{collection_id}/domain	Set collection domain
`DELETE`	/collections/{collection_id}/domain	Delete Collection Domain

Common Path Parameters

Parameter	Type	Description
collection_id (required)	string Any	ID of the Collection

Details

Get Endpoint Domain

GET /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 Domain Response

Table 1. application/json
Name	Type	Description
code	string `success`
data	array (object) ( link:Domain 1.0.0] )
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.

{
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "domain#1.0.0",
      "domain_name": "endpoint.example.org",
      "wildcard": true
    }
  ]
}

Put Endpoint Domain

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

application/json

Custom domain definition.

Name	Type	Description
body	Domain 1.0.0 One of { object Managed domain 1.0.0 , object Unmanaged domain 1.0.0 }	Custom domain definition.

Example

{
  "DATA_TYPE": "string",
  "domain_name": "custom.domain.org",
  "wildcard": true,
  "certificate": "string",
  "certificate_chain": "string",
  "private_key": "string"
}

Responses

200 - Put Domain Response

Table 2. application/json
Name	Type	Description
code	string `success`
data	array (object) ( link:Domain 1.0.0] )
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.

{
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "code": "success",
  "message": "Updated domain"
}

400 - Bad request

Delete Endpoint Domain

DELETE /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 Domain Response

Table 3. 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"
}

401 - Unauthorized

403 - Missing required role

404 - Not Found

Details

Get collection domain

GET /collections/{collection_id}/domain

Get the public info about the domain used by a collection.

Responses

200 - Get Domain Response

Table 4. application/json
Name	Type	Description
code	string `success`
data	array (object) ( link:Domain 1.0.0] )
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.

{
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "code": "success",
  "data": [
    {
      "DATA_TYPE": "domain#1.0.0",
      "domain_name": "endpoint.example.org",
      "wildcard": true
    }
  ]
}

400 - Bad request

404 - Not Found

Set collection domain

PUT /collections/{collection_id}/domain

Update the domain used by a collection to the value passed in to this call. If the domain is a wildcard domain and the collection is a mapped collection, then all guest collections created on this mapped collection will be updated to be subdomains of this domain rather than the endpoint domain.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Request body

application/json

Name

Type

Description

Example

{}

Responses

200 - Put Domain Response

Table 5. application/json
Name	Type	Description
code	string `success`
data	array (object) ( link:Domain 1.0.0] )
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.

{
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "code": "success",
  "message": "Updated domain"
}

400 - Bad request

401 - Unauthorized

403 - Missing required role

404 - Not Found

Delete Collection Domain

DELETE /collections/{collection_id}/domain

Delete the custom collection domain. It will be updated to use a random subdomain of the endpoint’s wildcard domain. If this is a mapped collection with a wildcard domain, then all guest collections on this mapped collection which do not have custom domains will also be reverted to using random domains. If this is a guest collection with a custom domain, it will be updated to use a random subdomain of the mapped collection if it has a wildcard domain or the endpoint if not.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Responses

200 - Delete Custom Collection Domain 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"
}