Globus Connect Personal Management

1. Overview

During the installation process of Globus Connect Personal, a collection definition will be created in Transfer for the Globus Connect Personal mapped collection. The Transfer API can then be used to update, delete, or create guest collections on the Globus Connect Personal mapped collection.

2. Document Types

2.1. Collection Document

The general endpoint or collection document is used for updating Globus Connect Personal collections.

2.2. Guest Collection Document

The guest collection document (DATA_TYPE of "shared_endpoint"[1]) document is a subtype of the endpoint or collection document used to create Globus Connect Personal guest collections.

Guest Collection Document Example
{
  "DATA_TYPE": "shared_endpoint",
  "display_name": "myguest",
  "host_endpoint": "e8ec21f6-de26-11ed-850f-3d7bd94376cd",
  "host_path": "/~/",
  "description": "Guest collection for sharing GCP data",
  "organization": "my org"
}

The guest collection document can include other informational fields like contact_email and keywords, and option fields like force_encryption (see the updatable field list and full endpoint or collection document for details). Note that guest collections are always public, and the location and network_use related fields are not settable because they are inherited from the parent mapped collection.

3. Path Arguments

Name Type Description

collection_id

string

The id field of the collection.

4. Common Query Parameters

Name Type Description

fields

string

Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed.

5. Common Errors

The error code can be found in the HTTP response body JSON document. See error overview .

Code HTTP Status Description

EndpointNotFound[1]

404

If <collection_id> not found.

PermissionDenied

403

If user does not have privileges to get, modify, or delete the specified collection(s).

ClientError.Conflict

409

If an endpoint with the same name already exists or if a role assignment with the same principal and role already exists.

ServiceUnavailable

503

If the service is down for maintenance.

6. Operations

6.1. Create guest collection

Create a guest collection on a Globus Connect Personal mapped collection. Once created, a Globus Connect Personal guest collection is managed using the same API resources as a Globus Connect Personal mapped collection and supports Permission Management for sharing data with guest users.

Authorization

Only allowed for the owner of the host Globus Connect Personal mapped collection, and requires that the mapped collection is subscribed.

URL

/shared_endpoint[1]

Method

POST

Request Body

Guest collection document

Response Body

Result document, including an id field containing the system generated id of the new collection.

6.2. Update Globus Connect Personal collection by id

Update a Globus Connect Personal collection. This can be done using a partial document by specifying only DATA_TYPE and the fields to be updated, or doing a GET on the collection, changing the appropriate fields, and doing a PUT of the full document. Using a partial document is preferred.

Authorization

Requires an "administrator" or "restricted_administrator" effective role on the collection.

URL

/endpoint/<collection_id>[1]

Method

PUT

Request Body

Partial collection document

Response Body

Result document

Which Globus Connect Personal collection fields can be updated depends on the type:

Type Updatable fields

Both Globus Connect Personal mapped and guest collections

contact_email, contact_info, default_directory, department, description, disable_verify, display_name, force_encryption, info_link, keywords, organization, owner_string, subscription_admin_verified

DEPRECATED: canonical_name, name

Globus Connect Personal mapped collections only

location, max_concurrency, max_parallelism, network_use, preferred_concurrency, preferred_parallelism, public, subscription_id

6.3. Delete Globus Connect Personal collection by id

Delete a Globus Connect Personal collection by id. Note that all data associated with the collection, including roles and permissions, will be deleted as well.

If the collection is a Globus Connect Personal mapped collection, any guest collections hosted on it will also be deleted.

Authorization

Requires an "administrator" or "restricted_administrator" effective role on the collection.

URL

/endpoint/<collection_id>[1]

Method

DELETE

Response Body

Result document

6.4. Associate a Globus Connect Personal Mapped Collection with a Subscription

Associate a Globus Connect Personal mapped collection with a subscription id to make it subscribed. Any guest collection children of the mapped collection inherit the subscription and cannot be directly associated with it themselves.

This resource has different authorization requirements depending on the user’s roles on the Globus subscription group and the mapped collection.

If the user has the administrator effective role on the Globus Connect Personal mapped collection, this resource can be used similarly to the Update Globus Connect Personal collection by id resource to remove any existing subscription_id from the collection or associate any subscription_id the user has subscription group membership for regardless of the collection’s current subscribed status.

Subscription managers and administrators may also use this resource to associate a Globus Connect Personal mapped collection with a subscription_id they manage, but only if the collection is unsubscribed or already associated with a subscription they manage. This allows Globus Connect Personal administrators to request a subscription be associated with the mapped collection without needing to give a subscription manager a role on the mapped collection.

URL

/endpoint/<collection_id>/subscription[1]

Method

PUT

Request Body

 
{
  "subscription_id": "4efbf767-60d5-4616-8627-589e2e01030c"
}

subscription_id can be either a UUID string matching the subscription_id of a subscription group the user has access to, or if the user has access to exactly one subscription the value "DEFAULT" may be given to use that subscription’s id.

Response Body

Result document

6.5. Set Subscription Admin Verified

Set subscription_admin_verified on a Globus Connect Personal collection. Setting the value to true indicates to users that the collection is operated and maintained by the subscribing organization.

This resource has different authorization requirements depending on the user’s roles on the Globus subscription group and the collection.

Subscription administrators can use this resource to grant or revoke verification on a collection that is associated with their subscription without needing an administrator role on the collection itself.

Users with the administrator effective role on the Globus Connect Personal collection can use this resource similarly to the Update Globus Connect Personal collection by id resource. A collection administrators can revoke verification without having an administrator role on the subscription group, but still must be a subscription administrator to verify the collection.

URL

/endpoint/<collection_id>/subscription_admin_verified[1]

Method

PUT

Request Body

 
{
  "subscription_admin_verified": true
}

Response Body

Result document
1. This use of the term "endpoint" is a case of legacy endpoint terminology and can also/exclusively refer to collections