globus-js
A package for interacting with the globus.org REST API.
Install
npm install --save-dev globus-js
TODO
- Format modules into API logical section
Task Submission- Task Monitoring
- File Operations
- Endpoint Management
- Endpoint Search
- Endpoint Roles
- Endpoint Bookmarks
Endpoint ACL
- Write script prepublish to construct minified globus.js file
- Reformat README to be more readable
- Add contributing documentation
- Move documentation to github wiki
API
getAccessRulesList
getAccessRulesList - Get the list of access rules in the ACL for a specified endpoint.
Parameters
bearerToken
string token authorized by globus.org.endpoint_xid
string the id of the endpoint you'd like to list ACL's from.
Returns promise containing the body of the response.
getAccessRulesListById
getAccessRulesListById - Get a single access rule for a specified endpoint by id.
Parameters
bearerToken
string token authorized by globus.org.endpoint_xid
string the id of the endpoint you'd like to get an ACL from.id
int Integer id of an access rule.
Returns promise containing the body of the response.
createAccessRule
createAccessRule - opens an access point with a given user. Shared endpoint_xid's can be found by looking at the details of the endpoint you want to piggy back off of.
Parameters
bearerToken
string token authorized by globus.org.endpoint_xid
string the id of the endpoint you'd like to base your share off of.userId
string the UUID of the user you'd like to share this endpoint withpath
string an absolute path to the resoureces you'd like to sharepermissions
string a combination of 'r', 'w', to give the user read and write permissionsuserEmail
string the email of the user you'd like to notifyemailMessage
string the message you'd like to attach to the e-mail
Returns promise containing the body of the response
updateAccessRule
updateAccessRule - Update the permissions on an existing access rule. Other fields (besides DATA_TYPE which must always be present) may be omitted. If the id is present it must match the id in the URL.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string the id of the endpoint you'd like to base your share off of.id
string Unique id for this access rule. Implicit access rules from "access_manager" role assignments will have a null id, see role_id.role_id
string descriptionprincipal_type
string Type of principal that the rule applies to. One of "identity", "group", or "all_authenticated_users" or "anonymous".principal
string The subject of the access rule; the interpretation depends on principal_type: See link here for options.path
string Absolute path to a directory the access rule applies to. The path must begin and end with a slash, and can’t contain un-normalized components "/../" or "/./". GridFTP endpoints and shared endpoints hosted on GridFTP endpoints also support home directory relative paths beginning with "/~/". The path is limited to 2000 characters after encoding; in practice this means 2000 ascii characters and slightly less when unicode is present and must be encoded.permissions
string How much permission to grant the principal specified in principal_type and principal. Either read-only, specified as "r", or read-write, specified as "rw".
Returns promise containing the body of the response
deleteAccessRule
deleteAccessRule - Delete a single access rule, specified by id. Returns a result document with code "Deleted" on success and HTTP status code 200, and an "AccessRuleNotFound" error if the rule has already been deleted. If the client is using a retry loop, both should be accepted as success in case the first successful attempt is disconnected after the request is processed but before the response is received by the client.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string the id of the endpoint you'd like to delete an ACL fromid
int Integer id of an access rule.
Returns promise containing the body of the response
getActivationRequirements
getActivationRequirements - Gets the activation requirements of a particular endpoint.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string UUID of endpoint you want to get the activation requirements for
Returns promise containing the body of the response
autoActivateEndpoint
autoActivateEndpoint - Attempt to auto activate an endpoint. The response will always contain a code field. If the code is "AutoActivateFailed", the response will also include an activation requirements document, which can be filled in and submited to activate. On success, it will return a result code of the form "AutoActivated.CREDENTIAL_SOURCE", where CREDENTIAL_SOURCE indicates the how the credential was acquired.
Parameters
bearerToken
type descriptionendpoint_xid
type description
Returns type description
activateEndpoint
activateEndpoint - To active an endpoint, clients should get the activation requirements for the endpoint (either explicitly or from the autoactivate result), pick an activation method, and fill in values for the chosen activation method. The requirements for the other methods not being used must be removed before submitting the request.
On success, it will return a result code of the form "Activated.TYPE", where TYPE indicates the type of activation used.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string UUID of endpoint you want to activateactivation_requirements_document
object a json object gotten from getActivationRequirements(..) with the required values filled in (https://docs.globus.org/api/transfer/endpoint_activation/#activation_requirements_document)
Returns promise containing the body of the response
deactivateEndpoint
deactivateEndpoint - Deactivates a endpoint given its UUID.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string UUID of endpoint you want to deactivate
Returns promise containing the body of the response
getUserId
getUserId - Given a token authorized by globus.org and a user's e-mail registered by globus it returns the user's id. Can be used in conjunction with shareEndpointWithUser's userId feild.
Parameters
Returns promise containing the body of the response
getEndpointById
getEndpointById - get's information about an endpoint given its endpoint_xid.
Parameters
Returns promise containing the body of the response
createEndpoint
createEndpoint - (UNTESTED) Create an endpoint. Which fields are required depends on the type of endpoint. Note that name and canonical_name are deprecated and supported only for backward compatibility; display_name should be used instead of, or in addition to, these fields. If canonical_name is not set, it will default to "USERNAME#ENDPOINT_UUID". At least one of them must be specified.
The result will include an id field containing the globally unique endpoint id, which should be used to further manipulate the endpoint document, and to perform transfers and other operations on the endpoint’s filesystem.
Parameters
bearerToken
string token authorized by globus.orgdisplay_name
string Friendly name for the endpoint, not unique. Unicode string, max 128 characters, no new lines (\r or \n). If not specified, will default to canonical_name, but that is deprecated and all new clients hould use id and display_name. Searchable.server_documents
array Array of server documents that each represents a network service that provides access to a filesystem. The most common type is a GridFTP server, which is represented by scheme "gsiftp". This is also the default scheme.
Returns promise containing the body of the response
createSharedEndpoint
createSharedEndpoint - creates a shared_endpoint endpoint that it's ACL can be editted to share paths with certain people.
Parameters
bearerToken
string token authorized by globus.orgdisplayName
string Friendly name for the endpoint, not unique. Unicode string, max 128 characters, no new lines (\r or \n). If not specified, will default to canonical_name, but that is deprecated and all new clients hould use id and display_name. Searchable.hostId
string Id of standard endpoint hosting the shared endpoint.path
string Root path being shared on the host endpoint.description
string A description of the endpoint. Unicode string, max length 4096 characters. Included in fulltext search.organization
string Organization that runs the server(s) represented by the endpoint. Optional to preserve backward compatibility, but will eventually be required and all clients are encouraged to require users to specify it. Unicode string, max 1024 characters, no new lines. Searchable.
Returns promise containing the body of the response
updateEndpointById
exports - Update an endpoint. 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 endpoint, changing the appropriate fields, and doing a PUT of the full document. Using a partial document is preferred.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string The UUID of the endpoint.partial_endpoint_document
object Look at this link for an explanation of a partial_endpoint_document based off of server and updated fields.
Returns promise containing the body of the response
deleteEndpointById
deleteEndpointById - Delete an endpoint by id or canonical name (the latter is deprecated). Only the owner can delete the endpoint. Note that all data associated with the endpoint, including roles and the ACL, will be deleted as well. If the hostname of the server has changed, the server document(s) in the endpoint should be changed rather than deleting and recreating the endpoint with different servers.
Parameters
Returns promise containing the body of the response
getEffectivePauseRuleList
getEffectivePauseRuleList - Get all pause rules on an endpoint that affect the current user, with sensitive administrator only fields removed.
Parameters
Returns promise containing the body of the response
getEndpointServerList
getEndpointServerList - Get a list of all servers belonging to the specified endpoint. Note that this is the same as the server list included under the "DATA" key of the endpoint document.
Parameters
Returns promise containing the body of the response
getEndpointServerById
getEndpointServerById - Get a specific server belonging to the specified endpoint.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string The UUID of the endpoint.server_id
string UUID of the server you want get.
Returns promise containing the body of the response
addEndpointServer
exports - Add a server to the specified endpoint. The hostname field is required, scheme and port default to "gsiftp" and 2811, and subject defaults to "null". The derived fields and boolean status fields are ignored, and should not be included in the request body. Returns a result document containing the id of the newly added server.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string The UUID of the endpoint.hostname
string Hostname of the server.uri
string URI of the server. This is a derived field combining the scheme, hostname, and port, and is not used when creating servers.port
string Port the server is listening on. Default: 2811.scheme
string URI scheme (protocol) used by the endpoint. Must be "gsiftp" or "ftp". Default: "gsiftp".
Returns promise containing the body of the response
updateEndpointServerById
updateEndpointServerById - Update a server belonging to the specified endpoint. Include only the fields to be updated in the request body - any of hostname, scheme, port, and subject can be updated.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string The UUID of the endpoint.server_id
type The UUID of the server you wish to update.hostname
string Hostname of the server.uri
string URI of the server. This is a derived field combining the scheme, hostname, and port, and is not used when creating servers.port
string Port the server is listening on. Default: 2811.scheme
string URI scheme (protocol) used by the endpoint. Must be "gsiftp" or "ftp". Default: "gsiftp".subject
string subject of the x509 certificate of the server. If not specified, the CN in the subject must match its hostname.
Returns promise containing the body of the response
deleteEndpointServerById
deleteEndpointServerById - Delete a server belonging to the specified endpoint.
Parameters
bearerToken
string token authorized by globus.orgendpoint_xid
string The UUID of the endpoint.server_id
type The UUID of the server you wish to update.
Returns promise containing the body of the response
getSharedEndpointList
getSharedEndpointList - Get a list of shared endpoints owned by the current user and hosted by a given GridFTP or Globus Connect Personal endpoint. Returns a "BadRequest" error if called on an endpoint that can’t host shared endpoints.
Parameters
Returns promise containing the body of the response
listDirectoryContents
listDirectoryContents - List the contents of the directory at the specified path on an endpoint’s filesystem. The endpoint must be activated before performing this operation.
The path is specified in the path query parameter. If the parameter is not passed, the default path depends on the type of endpoint
Parameters
bearerToken
string Token authorized by globus.org.endpoint_xid
string The id of the endpoint you'd like to get an ACL from.path
string (OPTIONAL) For shared endpoints, S3 endpoints, and anonymous FTP endpoints, the default is /. For GridFTP endpoints, the default is /~/. Most of the time this will map to the user’s home directory. However the administrator of the GridFTP server can configure it to point elsewhere. Also as a special case, if the restricted paths configuration on the server does not allow the user’s home directory, it will fall back to /.query_parameters
string (OPTIONAL) Added on query parameters to the end of the string (must be prefixed with an ampersand). Link
Returns promise containing the body of the response.
makeDirectory
makeDirectory - Create a directory at the specified path on an endpoint filesystem. The endpoint must be activated before performing this operation.
Parameters
bearerToken
string Token authorized by globus.org.endpoint_xid
string The id of the endpoint you'd like to get an ACL from.path
string For shared endpoints, S3 endpoints, and anonymous FTP endpoints, the default is /. For GridFTP endpoints, the default is /~/. Most of the time this will map to the user’s home directory. However the administrator of the GridFTP server can configure it to point elsewhere. Also as a special case, if the restricted paths configuration on the server does not allow the user’s home directory, it will fall back to /.
Returns promise containing the body of the response.
rename
rename - Rename or move a file or directory on an endpoint filesystem. The endpoint must be activated before performing this operation. When moving to a different parent directory, the parent directory of the new path must already exist.
Parameters
bearerToken
string Token authorized by globus.org.endpoint_xid
string The id of the endpoint you'd like to get an ACL from.old_path
type For shared endpoints, S3 endpoints, and anonymous FTP endpoints, the default is /. For GridFTP endpoints, the default is /~/. Most of the time this will map to the user’s home directory. However the administrator of the GridFTP server can configure it to point elsewhere. Also as a special case, if the restricted paths configuration on the server does not allow the user’s home directory, it will fall back to /.new_path
type For shared endpoints, S3 endpoints, and anonymous FTP endpoints, the default is /. For GridFTP endpoints, the default is /~/. Most of the time this will map to the user’s home directory. However the administrator of the GridFTP server can configure it to point elsewhere. Also as a special case, if the restricted paths configuration on the server does not allow the user’s home directory, it will fall back to /.
Returns promise containing the body of the response.
getSubmissionId
getSubmissionId - Get a submission id, required when submitting transfer and delete tasks. Note that this is different than the task id returned by the submit operations.
Parameters
bearerToken
string token authorized by globus.org
Returns promise containing the body of the response object
submitTransferTask
submitTransferTask - Submits a transfer task.
Parameters
bearerToken
string token authorized by globus.orgsubmission_id
string Id acquired from getSubmissionIdlabel
string user specified string to help identify the Transfer or delete task.notify_on_succeeded
boolean If true and the user has notification enabled, send a notification email when the transfer completes with status SUCCEEDED.notify_on_failed
boolean If true and the user has notification enabled, send a notification email when the transfer completes with status FAILED.notify_on_inactive
boolean If true and the user has notification enabled, send a notification email when the transfer enters status INACTIVE, e.g. from activation credentials expiring.source_endpoint
string UUID of the endpoint to transfer data from.destination_endpoint
string UUID of the endpoint to transfer data to.DATA
object List of transfer_item documents containing source and destination paths.encrypt_data
boolean If true, encrypt the data channel. If either the source or destination endpoint, or for shared endpoints the source or destination host endpoint, has force_encryption set, the data channel will be encrypted even if this is set to false.sync_level
integer review this link for information on this field.verify_checksum
boolean After transfer, verify that the source and destination file checksums match. If they don’t, re-transfer the entire file and keep trying until it succeeds.preserve_timestamp
boolean Preserve file modification time.delete_destination_extra
boolean Delete extraneous files in the destination directory. Only applies for recursive directory transfers.
Returns promise containing the body of the response object
submitDeletionTask
submitDeletionTask - Submit a delete task to globus
Parameters
bearerToken
string token authorized by globus.orgendpoint
string UUID of the endpoint containing the file system you want to delete fromDATA
object List of delete_item documents containing paths to delete.recursive
boolean Delete directory contents recursively. Required if any of the delete items point to a directory.ignore_missing
boolean Don’t generate errors for non existent files and directories.interpret_globs
boolean Interpret shell globs at the end of paths. Supports *, ?, [, and ] with their standard shell meanings and \ for escaping, but only in the last segment of the path. If false (the default), these special characters will be escaped and treated as literals.
Returns promise containing the body of the response object