Collection Bookmarks

1. Overview

Collection bookmarks allow a user to create an alias for a collection and path that they frequently use, and give it a custom name. The Globus Web Application and Globus CLI allow using bookmarks to quickly find commonly used collections and paths.

Bookmarks are always private to the user identity that creates them, and can’t be shared. A bookmark will be visible, editable, and deletable if the identity owning the bookmark is in the set of linked identities associated with the Globus Auth token used to authenticate with the API.

Note
Each user can have at most 100 bookmarks.
Note
If the collection pointed to by a bookmark is deleted, the bookmark will continue to exist and show up in bookmark_list results. This is to allow users to see that the deletion happened. Users can manually delete the bookmark once they see what happened.

2. Document Types

2.1. Bookmark Document

The "bookmark" document type represents a named alias for a Globus collection and path.

Bookmark Document Example
{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "genomics dataset1",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/genomics/dataset1/"
}

2.1.1. Bookmark Document Fields

Field Name JSON Type Description

DATA_TYPE

string

Always has value "bookmark" to indicate this document type. Optional in create requests.

id

string

Globally unique id string for this bookmark. This is system generated and should not be included in create requests.

name

string

Name of the bookmark, which will be used in searches. Unicode strings, with the following characters disallowed: '\n', '\r'. The name must be unique for each user. Note that spaces and special characters must be url encoded when using the bookmark in the Transfer CLI.

endpoint_id[1]

string

Id of the collection to bookmark.

path

string

Path to a directory on the collection. Must end in "/".

pinned

boolean

Is the bookmark pinned (a favorite). Default: false

3. Path Arguments

Name Type Description

bookmark_id

string

Unique identifier for a bookmark.

collection_id

string

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

BookmarkNotFound

404

If <bookmark_id> not found

EndpointNotFound[1]

404

If <collection_id> not found when creating a bookmark.

Conflict

409

If a bookmark with the same name owned by the current user already exists.

Exists

409

If a bookmark with the same endpoint_id and path already exists.

LimitExceeded

409

If the user already has the maximum of 100 bookmarks.

ServiceUnavailable

503

If the service is down for maintenance.

6. Operations

6.1. Get list of bookmarks

Get a list of bookmarks created by the current user.

URL

/bookmark_list

Method

GET

Response Body

 
{
  "DATA_TYPE": "bookmark_list",
  "DATA": [
    {
      "DATA_TYPE": "bookmark",
      "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
      "name": "genomics dataset1",
      "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
      "path": "/projects/genomics/dataset1/"
    },
    {
      "DATA_TYPE": "bookmark",
      "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
      "name": "physics dataset7",
      "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
      "path": "/projects/physics/dataset7/"
    }
  ]
}

6.2. Create bookmark

On success returns a copy of the created bookmark with the system generated id added.

Required fields: name, path, endpoint_id[1].

URL

/bookmark

Method

POST

Request Body

 
{
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

Response Body

 
{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

6.3. Get bookmark by id

Get a single bookmark by id.

URL

/bookmark/<bookmark_id>

Method

GET

Response Body

 
{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

6.4. Update bookmark

On success returns a copy of the updated bookmark. Only the name field can be updated. If other fields are included, they will be ignored, but clients are encouraged to pass only the name.

URL

/bookmark/<bookmark_id>

Method

PUT

Request Body

 
{
  "name": "physics dataset7"
}

Response Body

 
{
  "DATA_TYPE": "bookmark",
  "id": "1405823f-0597-4a16-b296-46d4f0ae4b15",
  "name": "physics dataset7",
  "endpoint_id": "a624df8b-8de2-4a73-a5b1-85b0f4bff2a8",
  "path": "/projects/physics/dataset7/"
}

6.5. Delete bookmark by id

Delete a single bookmark by id. Returns a result document on success.

URL

/bookmark/<bookmark_id>

Method

DELETE

Response Body

 
{
  "DATA_TYPE": "result",
  "code": "Deleted",
  "message": "Bookmark 'c67b666f-e1ad-4f67-af2c-48340dd12ada' deleted successfully",
  "resource": "/bookmark/a624df8b",
  "request_id": "ABCdef789"
}
1. This use of the term "endpoint" is a case of legacy endpoint terminology and can also/exclusively refer to collections