Endpoint Bookmarks

1. Overview

Endpoint bookmarks allow a user to create an alias for an endpoint and path that they frequently use, and give it a custom name. The globus.org website will allows using the bookmark to quickly find commonly used endpoints and paths, and other clients are free to provide this as a convenience to users as well. The CLI also allows direct usage of bookmarks (see the man pages), but the REST API does not support using bookmark names in place of endpoints elsewhere in the API. They are purely provided as a convenience to users.

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 endpoint 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 endpoint 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	string	Id of the endpoint to bookmark.
path	string	Path to a directory on the endpoint. 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.

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

Code	HTTP Status	Description
BookmarkNotFound	404	If <bookmark_id> not found
EndpointNotFound	404	If `endpoint_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/" } ] }

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, endpoint_id, path.

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	POST
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" }

Transfer API Menu