AgavePy Documentation¶

AgavePy is an open-source Python SDK that lets you to use Tapis (v2) services to manage data, perform computational analysis workflows, build automations, and more, all from within Python scripts or the Python interactive REPL.

You can view and fork the source code for AgavePy on GitHub. Join our community of users to provide feedback, request features, and submit your own contributions.

About Tapis¶

Tapis is an open source Science-as-a-Service API that powers research computing and data management workflows. Tapis unites high-performance computing (HPC), high-throughput computing (HTC), Cloud, and Big Data resources under a single, web-friendly REST API featuring fine-grained access control, detailed provenance, reproducibility, and scalability.

Example: List contents of a Tapis storageSystem path¶

To illustrate how one can use AgavePy, consider this example. Here, the Agave.files.list() function is used to return a Python list of the contents of a directory on a Tapis storage system.

>>> from agavepy import Agave
>>> ag = Agave.restore()
>>> files = ag.files.list(storageSystem='tacc-public-demo', filePath='/examples')

This same function can be accomplished by making an authenticated HTTP GET to the files API:

curl -XGET -H "Authentication: Bearer 24cace8cea8cd541012a323d9ebd2b6" \
'https://api.tacc.utexas.edu/files/v2/listings/system/files/v2/listings/system/tacc-public-demo/examples'

It could also be done using the Tapis CLI:

tapis files list agave://tacc-public-demo/examples

Making a direct API call requires more experience working with web services, but is extremely flexible. Using the CLI is very accessible, though it is a bit more opinionated and is also suited to interactive or script usage. AgavePy aims for the middle ground, providing an expressive, embeddable interface to Tapis that is closely aligned with the platform API’s syntax and usage.

Ultimately, your use case informs your choice of tooling - If you are interested in these other paths for working with Tapis, they are amply documented:

Tapis API docs : Research computing web services

Abaco API docs : Functions-as-a-Service for orchestration and integration

Tapis CLI docs : Shell environment for Tapis and Abaco

Installing AgavePy¶

The preferred, most compatible way to install AgavePy is to use PyPi. Current and all past releases are available unless deprecated to resolve security issues or functional defects.

pip install agavepy

For a specific version:

pip install agavepy==1.0.0

From source¶

You can also install the latest AgavePy releases from source.

Obtain the source code from GitHub¶

git clone https://github.com/TACC/agavepy

This will check out the master branch. To checkout an alternative branch (for example develop), do the following:

cd agavepy
git checkout develop

Install with setuptools¶

Within the agavepy source directory:

python setup.py install

Install with GNU make¶

If GNU make is installed in your system, you can install AgavePy for Python 3 as follows:

make install

You can install for Python 2 like so:

make install-py2

Tapis User Account¶

Tapis is a “multi-tenant” web service platform, which means it provides and manages logically-isolated resources. The main source for such isolation is how a user’s identity is confirmed. As a Tapis user, you need to know which tenant you wish to use. For most people, and for the purposes of this documentation, the TACC tenant (tacc.prod) will be the default and correct choice.

Thus, you will need an active TACC account. Go to the TUP and create an account, or, if you have a TACC account already, please confirm that you are able log into https://portal.tacc.utexas.edu with your TACC username and password.

Note

New TACC accounts must be confirmed via an email-based workflow before they are active, so please check your email and follow any validation instructions you find there.

Other Tenants¶

Documentation on account policy and management for other tenants (and Tapis sites) can be found here.

Site	Tenant	Credentials	Account Page
TACC	CyVerse	Cyverse username/password	https://user.cyverse.org/
TACC	DesignSafe	TACC username/password	https://www.designsafe-ci.org/account/register/
TACC	SGCI	TACC username/password	TBD
TACC	TACC	TACC username/password	https://portal.tacc.utexas.edu/account-request
TACC	3DEM	TACC username/password	https://3dem.org/help/portal-users-guide/
CDC	TBD	TBD	TBD

You may also consult the Tapis platform point of contact for each tenant directly.

Authenticating with Tapis¶

To interact with the Tapis APIs, you will need a Tapis platform account, an Oauth API client (created using your account credentials), and an access/refresh token pair (created using your Oauth client).

Oauth2 Overview¶

Tapis uses Oauth2 for authentication, which is a scheme to avoid sending your private username and password over the Internet. Without getting deeply into the details, here’s how it works. You provide your actual username and password once and get back a substitute set of credentials called an API Key and Secret. You then use those credentials to get a temporary (expires in a short time) access token which is used in place of the username, password, key, and secret to access APIs. If a hostile actor were to get access to your token, they will only have a brief window where it is valid, which is much more secure than having static credentials floating around on the Internet.

Getting a new token is simple: the access_token is returned with a refresh token, which can be redeemed once to get another access token. This can be done automatically (AgavePy does it for you) when the access token expires, or on-demand by you or your agent.

Create a Client¶

Create a Tapis API client using the following code.

>>> from agavepy import Agave
>>> ag = Agave(api_server='https://api.tacc.utexas.edu',
               username='tacobot',
               password='$uch9oOdT@coS')
>>> ag.clients_create()
{'api_key': 'fybMWk8H4ROzk0aBKCC3VeCvCE5V',
 'api_secret': 'XFsHQ8Vt7Wc37oQtyBLfa',
 'client_name': 'cariad-major-puma'}

Write down the API key and secret, as you will need them to configure AgavePy to use this client in the future. Also note the client name, as you can use it to refer to the client when performing management actions like changing its subscriptions or deleting it.

Generate an Access Token¶

Issuing your first access and refresh token requires you to specify api key and secret plus a username and password. This provides extra validation and protection since the resulting token pair can be chain-refreshed indefinitely until revoked. An AgavePy client automatically requests a token pair when initialized with valid credentials and API client details.

>>> from agavepy import Agave
>>> ag = Agave(api_server='https://api.tacc.utexas.edu',
               username='tacobot',
               password='$uch9oOdT@coS',
               api_key='fybMWk8H4ROzk0aBKCC3VeCvCE5V',
               api_secret='XFsHQ8Vt7Wc37oQtyBLfa')

You can confirm that the client ag is active by making an API query. Try ag.profiles.get(). Alternatively, you can view the current token pair with ag.tokens().

Refreshing the Token¶

The Agave.refresh() function will attempt to regenerate the access token, returning it as a string. If you need to discover the value of the refresh token, tokens() will do the trick.

>>> ag.refresh()
'b9ffb4ed6c3c3412d2e09de3b3defa33'
>>> ag.tokens()
{'access_token': 'b9ffb4ed6c3c3412d2e09de3b3defa33',
 'refresh_token': 'd941cc474ed4a2fcf93672b65f76195'}

Note

A properly initialized Agave client will attempt to refresh its own token automatically whenever the token appears to have expired. Thus, you do not generally need to worry about token management while working with AgavePy functions.

Local Credential Cache¶

Once a complete AgavePy client has been initialized, it stores a small plaintext file containing api key and secret, access token, and refresh token on the local file system. The default location for this cache file is in the directory $HOME/.agave/ but this can be overridden by setting the environment variable TAPIS_CACHE_DIR. This comes in handy because AgavePy has a built-in function for reading from the cache file. In a fresh Python REPL, try the following:

>>> from agavepy import Agave
>>> ag = Agave.restore()

Like we did earlier, you can confirm that the client ag is active by making an API query. Try ag.profiles.get(). Alternatively, you can view the current token pair with ag.tokens().

Special Cases¶

AgavePy’s standard workflow is optimized to support interactive scripting on systems where you have write access to the local filesystem, and where you are comfortable storing your API key and secret. Some environments, like Docker containers or public web services, don’t fit that mold. Thus, there are a couple of alternative paths to configure AgavePy for use by your application.

Access-Only Client¶

AgavePy can be set up as an access-only client using just an access token. This is helpful for short-term usage, but does require the access token be generated using another means. Also, the token will be active no more than an hour. Keep these limitations in mind when designing an implementation that relies on an access-only API client.

>>> from agavepy import Agave
>>> ag = Agave(api_server='https://api.tacc.utexas.edu',
...            token='b9ffb4ed6c3c3412d2e09de3b3defa33')
>>> ag.profiles.get()
{'first_name': 'Taco', 'last_name': 'Bot', 'full_name': 'tacobot',
 'email': 'tacobot@tacc.cloud',
 'phone': '', 'mobile_phone': '', 'status': '', 'create_time': '20140515180317Z',
 'uid': 806444, 'username': 'tacobot'}

Environment Variables¶

By setting various configurations of environment variables, AgavePy can be initialized directly from the environment with no cache file required via Agave.restore(). The capabilities of the client will be based on which variables were set. For example, a Standard client can issue and re-issue access tokens indefinitely, while an Access-Only* client can access Tapis APIs only for the active duration of the token passed as TAPIS_API_TOKEN.

Variable	Standard	Access-Only	Token-Refresh	Bare-Refresh	Client-Manager	Token-Generator
`TAPIS_BASE_URL`	X	X	X	X	X	X
`TAPIS_API_KEY`	X		X			X
`TAPIS_API_SECRET`	X		X			X
`TAPIS_API_TOKEN`		X	X	X
`TAPIS_API_REFRESH_TOKEN`			X	X
`TAPIS_API_USERNAME`	X				X	X
`TAPIS_API_PASSWORD`	X				X	X

Note

Environment variables are not updated by the AgavePy library. For example, if TAPIS_API_TOKEN expires, the client will no longer have access to Tapis APIs. Or, if a Token-Refresh client is created, it must track any new values for the access and refresh tokens after Agave.refresh() is invoked, since the environment variable values will no longer be valid.

The AgavePy client¶

The core aspect of an initialized AgavePy client is a submodule and function structure that mirrors the Swagger 1.2 specification for the Tapis APIs.

>>> from agavepy import Agave
>>> ag = Agave.restore()
>>> # find available APIs
>>> dir(ag)
['actors', 'admin', 'apps', 'clients', 'files', 'jobs', 'meta', 'monitors',
'notifications', 'postits', 'profiles', 'systems', 'transforms']
>>> # inspect functions available for the 'apps' API
>>> dir(ag.apps)
['add', 'delete', 'deletePermissions', 'deletePermissionsForUser', 'get',
'getJobSubmissionForm', 'list', 'listByName', 'listByOntologyTerm', 'listBySystemId',
'listByTag', 'listPermissions', 'listPermissionsForUser', 'manage', 'update',
'updateApplicationPermissions', 'updatePermissionsForUser']

Unfortunately, because AgavePy is metaprogrammed from the Swagger specification, the help text for the individual functions is not available. As an alternative, you can look up the function help here in the AgavePy docs in the section Use AgavePy with Tapis APIs.

Specifying Parameters¶

In the table below are some common parameters, a list of services that accept them for at least one command, and a description of what they are. Usage examples are shown below the table.

Keyword Argument	Service(s)	Description
`actorId`, `executionId`, `nonceId`, `workerId`	actors	String hashed identifier
`appId`, `systemId`	apps, jobs, systems	String distinct identifier
`jobId`, `uuid`	jobs, metadata, notifications	String UUID
`filePath`	apps, jobs, notifications	String path relative to `/` on a storage system
`body`	actors, apps, jobs, notifications, metadata, systems	JSON document conforming to an API+function schema
`limit`	apps, jobs, notifications, metadata, systems	integer <= 300
`offset`	apps, jobs, notifications, metadata, systems	integer >= 0

Note

All values must be passed as keyword arguments in AgavePy. A common coding convention is that Python keyword arguments can be passed positionally. This isn’t a safe assumption when using AgavePy due to some low-level details of how the library is implemented.

Refer to a specific Tapis entity by its identifier¶

>>> # show a specific app
>>> ag.apps.get(appId='prodigal-2.6.3u3')
{'id': 'prodigal-2.6.3u3', ..., 'outputs': []}
>>> #
>>> # show a specific system
>>> ag.systems.get(systemId='data.iplantcollaborative.org')
{'owner': 'cyverse', ..., 'status': 'UP'}
>>> #
>>> # inspect a job
>>> ag.jobs.getStatus(jobId='6632084267285418471-242ac113-0001-007')
{'id': '6632084267285418471-242ac113-0001-007', 'status': 'FINISHED'}

Call a function requiring a body parameter¶

>>> # disable an app using its 'manage' function
>>> ag.apps.manage(appId='prodigal-2.6.3', body={'action': 'disable'})
{'id': 'prodigal-2.6.3', ..., 'available': False}

Pagination Options¶

Any Tapis API operations (save for the Abaco API) that implement a list operation accept pagination options limit and offset.

>>> # show applications 51-100
>>> ag.apps.list(limit=50, offset=50)

Reponses from AgavePy¶

All AgavePy commands return a Python dictionary, deserialized from a JSON response sent by the relevant Tapis API. This dictionary corresponds to the result key in the API JSON response.

Interpreting Errors¶

TBD

Systems¶

These functions help you to discover, inspect, share, and manage Tapis execution (compute) and storage (data) systems.

systems¶

Summary: Register and manage systems

add: Add or update a system.¶

systems.add(body=<BODY>)

Keyword Args:¶

body: The description of the system to add or update. (JSON, SystemRequest)

SystemRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/SystemRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "description": {
      "description": "Verbose description of this system.",
      "type": "string"
    },
    "environment": {
      "description": "Environment variables to set upon login prior to job submission.",
      "type": "string"
    },
    "executionType": {
      "description": "The execution paradigm used to run jobs on this system.",
      "enum": [
        "HPC",
        "CONDOR",
        "CLI"
      ],
      "type": "string"
    },
    "id": {
      "description": "Unique identifier for this system.",
      "type": "string"
    },
    "login": {
      "description": "The login config defining how to connect to this system for job submission.",
      "type": "LoginConfig"
    },
    "maxSystemJobs": {
      "description": "The maximum number of jobs that can be simultaneously run on the system across all queues.",
      "type": "int"
    },
    "maxSystemJobsPerUser": {
      "description": "The maximum number of jobs that can be simultaneously run on the system across all queues by a single user.",
      "type": "int"
    },
    "name": {
      "description": "Common name for this system.",
      "type": "string"
    },
    "queues": {
      "description": "The execution paradigm used to run jobs on this system.",
      "type": "array"
    },
    "scheduler": {
      "description": "The type of scheduled used to run jobs.",
      "enum": [
        "COBALT",
        "CONDOR",
        "FORK",
        "LOADLEVELER",
        "LSF",
        "MOAB",
        "PBS",
        "SGE",
        "SLURM",
        "TORQUE",
        "UNKNOWN"
      ],
      "type": "string"
    },
    "scratchDir": {
      "description": "The scratch directory where job execution directories will be created at runtime. The workDir is used if this is not specified.",
      "type": "string"
    },
    "site": {
      "description": "The site associated with this system.",
      "type": "string"
    },
    "startupScript": {
      "description": "Script to be run after login and prior to execution.",
      "type": "string"
    },
    "status": {
      "description": "The status of this system. Systems must be in UP status to be used.",
      "enum": [
        "UP",
        "DOWN",
        "UNKNOWN"
      ],
      "type": "string"
    },
    "storage": {
      "description": "The storage config defining how to connect to this system for data staging.",
      "type": "StorageConfig"
    },
    "type": {
      "description": "The type of this system.",
      "enum": [
        "EXECUTION",
        "STORAGE"
      ],
      "type": "string"
    },
    "workDir": {
      "description": "The work directory where job execution directories will be created at runtime. This is used if scratchDir is not specified. If neither are specified, the job directory will be created in the system homeDir.",
      "type": "string"
    }
  },
  "required": [
    "status",
    "queues",
    "storage",
    "executionType",
    "scheduler",
    "login",
    "type",
    "name"
  ],
  "title": "AgavePy SystemRequest schema",
  "type": "object"
}

Response:¶

A single System object

list: Show all systems available to the user.¶

systems.list(default=None, limit=250, offset=0, public=None, type=None)

Keyword Args:¶

default: Should only default systems be returned (boolean, optional)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

public: Should only publicly available systems be returned (boolean, optional)

type: The type of system to return (string, optional)

Response:¶

Array of SystemSummary objects

delete: Delete a system.¶

systems.delete(systemId=<SYSTEMID>)

Keyword Args:¶

systemId: The unique id of the system (string)

Response:¶

String

get: Find information about an individual system.¶

systems.get(systemId=<SYSTEMID>)

Keyword Args:¶

systemId: The unique id of the system (string)

Response:¶

A single System object

manage: Perform a management action on the system.¶

systems.manage(body=<BODY>, systemId=<SYSTEMID>)

Keyword Args:¶

body: The description of the system to update. (JSON, SystemOperationRequest)

systemId: The unique id of the system (string)

Response:¶

String

update: Find information about an individual system.¶

systems.update(body=<BODY>, systemId=<SYSTEMID>)

Keyword Args:¶

body: The description of the system to update. (JSON, SystemRequest)

systemId: The unique id of the system (string)

Response:¶

A single System object

deleteRoles: Deletes all roles on a system.¶

systems.deleteRoles(systemId=<SYSTEMID>)

Keyword Args:¶

systemId: The id of the system. (string)

Response:¶

String

listRoles: Get a list of all users and their roles on this system.¶

systems.listRoles(limit=250, offset=0, systemId=<SYSTEMID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

systemId: The id of the system. (string)

Response:¶

Array of SystemRole objects

updateRole: Add or update a user’s role on a system.¶

systems.updateRole(body=<BODY>, systemId=<SYSTEMID>)

Keyword Args:¶

body: The role to update. (JSON, SystemRole)

systemId: The id of the system. (string)

Response:¶

String

deleteRoleForUser: Deletes all roles on a system.¶

systems.deleteRoleForUser(systemId=<SYSTEMID>, username=<USERNAME>)

Keyword Args:¶

systemId: The id of the system. (string)

username: The username of the api user associated with the role (string)

Response:¶

String

getRoleForUser: Get a specific user’s roles on this system.¶

systems.getRoleForUser(limit=250, offset=0, systemId=<SYSTEMID>, username=<USERNAME>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

systemId: The id of the system. (string)

username: The username of the user about whose role you are inquiring. (string)

Response:¶

A single SystemRole object

updateRoleForUser: Add or update a user’s role on a system.¶

systems.updateRoleForUser(body=<BODY>, systemId=<SYSTEMID>, username=<USERNAME>)

Keyword Args:¶

body: The role to update. (JSON, SystemRole)

systemId: The id of the system. (string)

username: The username of the api user associated with the role (string)

Response:¶

String

deleteCredentials: Deletes all credentials registered to a system.¶

systems.deleteCredentials(systemId=<SYSTEMID>)

Keyword Args:¶

systemId: The id of the system. (string)

Response:¶

String

deleteCredentialsForInternalUser: Deletes all credentials registered to a system.¶

systems.deleteCredentialsForInternalUser(internalUsername=<INTERNALUSERNAME>, systemId=<SYSTEMID>)

Keyword Args:¶

internalUsername: The username of a internal user on this system. (string)

systemId: The id of the system. (string)

Response:¶

String

Files¶

These functions help you to upload, download, discover, inspect, share, and administer files and folders managed by Tapis storage systems.

files¶

Summary: Move and manage data

deleteFromDefaultSystem: Deletes a file or folder.¶

files.deleteFromDefaultSystem(sourcefilePath=<SOURCEFILEPATH>)

Keyword Args:¶

sourcefilePath: The path of the file relative to the user’s default storage location. (string)

Response:¶

String

downloadFromDefaultSystem: Download a file from the user’s default storage location.¶

files.downloadFromDefaultSystem(sourcefilePath=<SOURCEFILEPATH>)

Keyword Args:¶

sourcefilePath: The path of the file relative to the user’s default storage location. (string)

Response:¶

None

importToDefaultSystem: Import a file via direct upload or importing from a url to the user’s default storage location.¶

files.importToDefaultSystem(callbackURL=None, fileName=None, fileToUpload=None, fileType=None, sourcefilePath=<SOURCEFILEPATH>, urlToIngest=None)

Keyword Args:¶

callbackURL: The URI to notify when the import is complete. This can be an email address or http URL. If a URL is given, a GET will be made to this address. URL templating is supported. Valid template values are: ${NAME}, ${SOURCE_FORMAT}, ${DEST_FORMAT}, ${STATUS} (string, optional)

fileName: The name of the file after importing. If not specified, the uploaded file name will be used. (string, optional)

fileToUpload: The file object to import. (void, optional)

fileType: The file format this file is in. Defaults to raw. This will be used in file transform operations. (string, optional)

sourcefilePath: The path of the file relative to the user’s default storage location. (string)

urlToIngest: The URL to import the file from. This parameter is used if not file is uploaded with this post. (string, optional)

Response:¶

A single RemoteFile object

manageOnDefaultSystem: Perform an action on a file or folder.¶

files.manageOnDefaultSystem(body=<BODY>, sourcefilePath=<SOURCEFILEPATH>)

Keyword Args:¶

body: The operation to perform. (JSON, FileOperationRequest)

sourcefilePath: The path of the file relative to the user’s default storage location. (string)

Response:¶

String

delete: Deletes a file or folder.¶

files.delete(filePath=<FILEPATH>, systemId=<SYSTEMID>)

Keyword Args:¶

filePath: The path of the file relative to the user’s default storage location. (string)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

String

download: Download a file from the user’s default storage location.¶

files.download(filePath=<FILEPATH>, systemId=<SYSTEMID>)

Keyword Args:¶

filePath: The path of the file relative to the user’s default storage location. (string)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

None

importData: Import a file via direct upload or importing from a url to the user’s default storage location.¶

files.importData(callbackURL=None, fileName=None, filePath=<FILEPATH>, fileToUpload=None, fileType=None, notifications=[], systemId=<SYSTEMID>, urlToIngest=None)

Keyword Args:¶

callbackURL: The URI to notify when the import is complete. This can be an email address or http URL. If a URL is given, a GET will be made to this address. URL templating is supported. Valid template values are: ${NAME}, ${SOURCE_FORMAT}, ${DEST_FORMAT}, ${STATUS} (string, optional)

fileName: The name of the file after importing. If not specified, the uploaded file name will be used. (string, optional)

filePath: The path of the file relative to the user’s default storage location. (string)

fileToUpload: The file object to import. (void, optional)

fileType: The file format this file is in. Defaults to raw. This will be used in file transform operations. (string, optional)

notifications: A list of notification objects to apply to the transfer. (FileNotificationRequest, optional)

systemId: The unique id of the system on which the data resides. (string)

urlToIngest: The URL to import the file from. This parameter is used if not file is uploaded with this post. (string, optional)

Response:¶

A single RemoteFile object

manage: Perform an action on a file or folder.¶

files.manage(body=<BODY>, filePath=<FILEPATH>, systemId=<SYSTEMID>)

Keyword Args:¶

body: The operation to perform. (JSON, FileOperationRequest)

filePath: The path of the file relative to the user’s default storage location. (string)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

String

listOnDefaultSystem: Get a remote directory listing.¶

files.listOnDefaultSystem(filePath=<FILEPATH>, limit=250, offset=0)

Keyword Args:¶

filePath: The path of the file relative to the user’s default storage location. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of RemoteFile objects

list: Get a remote directory listing on a specific system.¶

files.list(filePath=<FILEPATH>, limit=250, offset=0, systemId=<SYSTEMID>)

Keyword Args:¶

filePath: The path of the file relative to the user’s default storage location. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

Array of RemoteFile objects

getHistoryOnDefaultSystem: Download a file from the user’s default storage location.¶

files.getHistoryOnDefaultSystem(filePath=<FILEPATH>, limit=250, offset=0)

Keyword Args:¶

filePath: The path of the file relative to the user’s default storage location. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of FileHistory objects

getHistory: Return history of api actions.¶

files.getHistory(filePath=<FILEPATH>, limit=250, offset=0, systemId=<SYSTEMID>)

Keyword Args:¶

filePath: The path of the file relative to the given system root location. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

Array of FileHistory objects

updatePermissionsOnDefaultSystem: Update permissions for a single user.¶

files.updatePermissionsOnDefaultSystem(body=<BODY>, filePath=<FILEPATH>)

Keyword Args:¶

body: The permission add or update. (JSON, FilePermissionRequest)

filePath: The path of the file relative to the user’s default storage location. (string)

Response:¶

String

deletePermissions: Deletes all permissions on a file except those of the owner.¶

files.deletePermissions(filePath=<FILEPATH>, systemId=<SYSTEMID>)

Keyword Args:¶

filePath: The path of the file relative to the user’s default storage location. (string)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

String

updatePermissions: Update permissions for a single user.¶

files.updatePermissions(body=<BODY>, filePath=<FILEPATH>, systemId=<SYSTEMID>)

Keyword Args:¶

body: The permission add or update. (JSON, FilePermissionRequest)

filePath: The path of the file relative to the user’s default storage location. (string)

systemId: The unique id of the system on which the data resides. (string)

Response:¶

Array of FilePermission objects

Apps¶

These functions help you to discover, inspect, share, and manage Tapis apps.

apps¶

Summary: Register and manage apps

add: Register and update new applications.¶

apps.add(body=<BODY>)

Keyword Args:¶

body: The description of the app to add or update. (JSON, ApplicationRequest)

ApplicationRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ApplicationRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "available": {
      "description": "Whether the application is available.",
      "type": "boolean"
    },
    "checkpointable": {
      "description": "Whether the application supports checkpointing.",
      "type": "boolean"
    },
    "defaultMaxRunTime": {
      "description": "The max execution time that should be used if none is given in a job description. Ignore if the system does not support schedulers.",
      "type": "int"
    },
    "defaultMemory": {
      "description": "The default memory in GB to pass to the scheduler if none is given in the job description. This must be less than the max memory parameter in the target queue definition.",
      "type": "string"
    },
    "defaultNodeCount": {
      "description": "The number of nodes that should be used if none is given in a job description. Ignore if the system does not support schedulers.",
      "type": "string"
    },
    "defaultProcessors": {
      "description": "The number of processors to pass to the scheduler if none are given in the job description. This must be 1 if the app is serial.",
      "type": "int"
    },
    "defaultQueue": {
      "description": "The queue on the execution system that should be used if none is given in a job description. Ignore if the system does not support schedulers.",
      "type": "string"
    },
    "deploymentPath": {
      "description": "The location in the user's default storage system containing the application wrapper and dependencies.",
      "type": "string"
    },
    "deploymentSystem": {
      "description": "The system id of the storage system where this app should run.",
      "type": "string"
    },
    "executionSystem": {
      "description": "The system id of the execution system where this app should run.",
      "type": "string"
    },
    "executionType": {
      "description": "The execution type of the application. If you're unsure, it's probably HPC.",
      "enum": [
        "ATMOSPHERE",
        "HPC",
        "CONDOR",
        "CLI"
      ],
      "type": "string"
    },
    "helpURI": {
      "description": "The URL where users can go for more information about the app.",
      "type": "string"
    },
    "icon": {
      "description": "The icon to associate with this app.",
      "type": "string"
    },
    "inputs": {
      "description": "The inputs files for this application. ",
      "type": "array"
    },
    "label": {
      "description": "The label to use when generating forms.",
      "type": "string"
    },
    "longDescription": {
      "description": "The full text description of this input to use when generating forms.",
      "type": "string"
    },
    "modules": {
      "description": "An array of modules to load prior to the execution of the application.",
      "type": "array"
    },
    "name": {
      "description": "The name of the application. The name does not have to be unique, but the combination of name and version does.",
      "type": "string"
    },
    "ontology": {
      "description": "An array of ontology values describing this application.",
      "type": "array"
    },
    "outputs": {
      "description": "The outputs files for this application. ",
      "type": "array"
    },
    "parallelism": {
      "description": "The parallelism type of the application. If you're unsure, it's probably SERIAL.",
      "enum": [
        "SERIAL",
        "PARALLEL",
        "PTHREAD"
      ],
      "type": "string"
    },
    "parameters": {
      "description": "The inputs parameters for this application. ",
      "type": "array"
    },
    "shortDescription": {
      "description": "The short description of this application.",
      "type": "string"
    },
    "tags": {
      "description": "An array of tags related to this application.",
      "type": "array"
    },
    "templatePath": {
      "description": "The path to the wrapper script relative to the deploymentPath.",
      "type": "string"
    },
    "testPath": {
      "description": "The path to the test script relative to the deploymentPath.",
      "type": "string"
    },
    "version": {
      "description": "The version of the application in #.#.# format. While the version does not need to be unique, the combination of name and version does have to be unique.",
      "type": "string"
    }
  },
  "required": [
    "executionType",
    "parameters",
    "version",
    "templatePath",
    "available",
    "inputs",
    "executionSystem",
    "testPath",
    "deploymentPath",
    "deploymentSystem",
    "name"
  ],
  "title": "AgavePy ApplicationRequest schema",
  "type": "object"
}

Response:¶

A single Application object

list: Get a list of available applications.¶

apps.list(limit=250, offset=0, privateOnly=None, publicOnly=None)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

privateOnly: Whether to return only private apps. (boolean, optional)

publicOnly: Whether to return only public apps. (boolean, optional)

Response:¶

Array of ApplicationSummary objects

delete: Deletes an application.¶

apps.delete(appId=<APPID>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

Response:¶

String

get: Get details of an application by it’s unique id.¶

apps.get(appId=<APPID>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

Response:¶

A single Application object

manage: Edit an application.¶

apps.manage(appId=<APPID>, body=<BODY>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

body: The operation to perform. (JSON, ApplicationOperationRequest)

ApplicationOperationRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ApplicationOperationRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "action": {
      "description": "Action to perform on the file or folder.",
      "enum": [
        "publish",
        "clone"
      ],
      "type": "string"
    },
    "deploymentPath": {
      "description": "Path to the on cloned app's deployment folder on its storage system. Only used with the clone action.",
      "type": "string"
    },
    "executionSystem": {
      "description": "System on which the clone apps should run. Only used with the clone action.",
      "type": "string"
    },
    "name": {
      "description": "Name of cloned app. Only used with the clone action.",
      "type": "string"
    },
    "storageSystem": {
      "description": "Storage system on which the cloned app's assets resides. Only used with the clone action.",
      "type": "string"
    },
    "version": {
      "description": "Version of the cloned app. Only used with the clone action.",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "title": "AgavePy ApplicationOperationRequest schema",
  "type": "object"
}

Response:¶

A single Application object

update: Update an application.¶

apps.update(appId=<APPID>, body=<BODY>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

body: The description of the app to add or update. (JSON, ApplicationRequest)

ApplicationRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ApplicationRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "available": {
      "description": "Whether the application is available.",
      "type": "boolean"
    },
    "checkpointable": {
      "description": "Whether the application supports checkpointing.",
      "type": "boolean"
    },
    "defaultMaxRunTime": {
      "description": "The max execution time that should be used if none is given in a job description. Ignore if the system does not support schedulers.",
      "type": "int"
    },
    "defaultMemory": {
      "description": "The default memory in GB to pass to the scheduler if none is given in the job description. This must be less than the max memory parameter in the target queue definition.",
      "type": "string"
    },
    "defaultNodeCount": {
      "description": "The number of nodes that should be used if none is given in a job description. Ignore if the system does not support schedulers.",
      "type": "string"
    },
    "defaultProcessors": {
      "description": "The number of processors to pass to the scheduler if none are given in the job description. This must be 1 if the app is serial.",
      "type": "int"
    },
    "defaultQueue": {
      "description": "The queue on the execution system that should be used if none is given in a job description. Ignore if the system does not support schedulers.",
      "type": "string"
    },
    "deploymentPath": {
      "description": "The location in the user's default storage system containing the application wrapper and dependencies.",
      "type": "string"
    },
    "deploymentSystem": {
      "description": "The system id of the storage system where this app should run.",
      "type": "string"
    },
    "executionSystem": {
      "description": "The system id of the execution system where this app should run.",
      "type": "string"
    },
    "executionType": {
      "description": "The execution type of the application. If you're unsure, it's probably HPC.",
      "enum": [
        "ATMOSPHERE",
        "HPC",
        "CONDOR",
        "CLI"
      ],
      "type": "string"
    },
    "helpURI": {
      "description": "The URL where users can go for more information about the app.",
      "type": "string"
    },
    "icon": {
      "description": "The icon to associate with this app.",
      "type": "string"
    },
    "inputs": {
      "description": "The inputs files for this application. ",
      "type": "array"
    },
    "label": {
      "description": "The label to use when generating forms.",
      "type": "string"
    },
    "longDescription": {
      "description": "The full text description of this input to use when generating forms.",
      "type": "string"
    },
    "modules": {
      "description": "An array of modules to load prior to the execution of the application.",
      "type": "array"
    },
    "name": {
      "description": "The name of the application. The name does not have to be unique, but the combination of name and version does.",
      "type": "string"
    },
    "ontology": {
      "description": "An array of ontology values describing this application.",
      "type": "array"
    },
    "outputs": {
      "description": "The outputs files for this application. ",
      "type": "array"
    },
    "parallelism": {
      "description": "The parallelism type of the application. If you're unsure, it's probably SERIAL.",
      "enum": [
        "SERIAL",
        "PARALLEL",
        "PTHREAD"
      ],
      "type": "string"
    },
    "parameters": {
      "description": "The inputs parameters for this application. ",
      "type": "array"
    },
    "shortDescription": {
      "description": "The short description of this application.",
      "type": "string"
    },
    "tags": {
      "description": "An array of tags related to this application.",
      "type": "array"
    },
    "templatePath": {
      "description": "The path to the wrapper script relative to the deploymentPath.",
      "type": "string"
    },
    "testPath": {
      "description": "The path to the test script relative to the deploymentPath.",
      "type": "string"
    },
    "version": {
      "description": "The version of the application in #.#.# format. While the version does not need to be unique, the combination of name and version does have to be unique.",
      "type": "string"
    }
  },
  "required": [
    "executionType",
    "parameters",
    "version",
    "templatePath",
    "available",
    "inputs",
    "executionSystem",
    "testPath",
    "deploymentPath",
    "deploymentSystem",
    "name"
  ],
  "title": "AgavePy ApplicationRequest schema",
  "type": "object"
}

Response:¶

A single Application object

deletePermissions: Deletes all permissions on an application.¶

apps.deletePermissions(appId=<APPID>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

Response:¶

String

listPermissions: Get the permission ACL for this application.¶

apps.listPermissions(appId=<APPID>, limit=250, offset=0)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of ApplicationPermission objects

updateApplicationPermissions: Add or update a user’s permission for an application.¶

apps.updateApplicationPermissions(appId=<APPID>, body=<BODY>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

body: The permission add or update. (JSON, ApplicationPermissionRequest)

ApplicationPermissionRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ApplicationPermissionRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "permission": {
      "description": "The permission to set",
      "enum": [
        "READ",
        "WRITE",
        "EXECUTE",
        "READ_WRITE",
        "READ_EXECUTE",
        "WRITE_EXECUTE",
        "ALL",
        "NONE"
      ],
      "type": "string"
    },
    "username": {
      "description": "The username of the api user whose permission is to be set.",
      "type": "string"
    }
  },
  "required": [
    "username",
    "permission"
  ],
  "title": "AgavePy ApplicationPermissionRequest schema",
  "type": "object"
}

Response:¶

String

deletePermissionsForUser: Deletes all permissions for the given user on an application.¶

apps.deletePermissionsForUser(appId=<APPID>, username=<USERNAME>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

username: The username of the api user associated with the permission (string)

Response:¶

String

listPermissionsForUser: Get a specific user’s permissions for an application.¶

apps.listPermissionsForUser(appId=<APPID>, limit=250, offset=0, username=<USERNAME>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

username: The username of the api user associated with the permission. (string)

Response:¶

Array of ApplicationPermission objects

updatePermissionsForUser: Add or update a user’s permission for an application.¶

apps.updatePermissionsForUser(appId=<APPID>, body=<BODY>, username=<USERNAME>)

Keyword Args:¶

appId: The id of the application. The application id is made up of the name and version separated by a dash. (string)

body: The permission add or update. (JSON, ApplicationPermissionRequest)

username: The username of the api user associated with the permission (string)

Response:¶

String

listByName: Get a list of applications with the given name.¶

apps.listByName(limit=250, name=<NAME>, offset=0, privateOnly=None, publicOnly=None)

Keyword Args:¶

limit: The max number of results. (integer, optional)

name: The name of the application. This should not include the version number. (string)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

privateOnly: Whether to return only private apps. (boolean, optional)

publicOnly: Whether to return only public apps. (boolean, optional)

Response:¶

Array of ApplicationSummary objects

listBySystemId: Get a list of applications with the given systemId as their executionHost.¶

apps.listBySystemId(limit=250, offset=0, privateOnly=None, publicOnly=None, systemId=<SYSTEMID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

privateOnly: Whether to return only private apps. (boolean, optional)

publicOnly: Whether to return only public apps. (boolean, optional)

systemId: The system in question (string)

Response:¶

Array of ApplicationSummary objects

Jobs¶

These functions help you to submit, monitor, inspect, share, and manage Tapis compute jobs.

jobs¶

Summary: Run and manage jobs

list: Get a list of jobs the authenticated user had submitted.¶

jobs.list(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of JobSummary objects

submit: Submit a new job request.¶

jobs.submit(body=<BODY>)

Keyword Args:¶

body: The description of the job to submit. This can be either a file upload or json posted to the request body. (JSON, JobRequest)

JobRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/JobRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "appId": {
      "description": "The unique name of the application being run by this job. This must be a valid application that the calling user has permission to run.",
      "type": "string"
    },
    "archive": {
      "description": "Whether the output from this job should be archived. If true, all new files created by this application's execution will be archived to the archivePath in the user's default storage system.",
      "type": "boolean"
    },
    "archivePath": {
      "description": "The path of the archive folder for this job on the user's default storage sytem.",
      "type": "string"
    },
    "archiveSystem": {
      "description": "The unique id of the storage system on which this job's output will be staged.",
      "type": "string"
    },
    "batchQueue": {
      "description": "The queue to which this job should be submitted. This is optional and only applies when the execution system has a batch scheduler.",
      "type": "string"
    },
    "inputs": {
      "description": "The application specific input files needed for this job. These vary from application to application and should be entered as multiple individual parameters in the form. Inputs may be given as relative paths in the user's default storage system or as URI. If a URI is given, the data will be staged in by the IO service and made avaialble to the application at run time.",
      "type": "JobInputs"
    },
    "maxRunTime": {
      "description": "The requested compute time needed for this application to complete given in HH:mm:ss format.",
      "type": "string"
    },
    "memoryPerNode": {
      "description": "The requested memory for this application to run given in GB.",
      "type": "string"
    },
    "name": {
      "description": "The name of the job.",
      "type": "string"
    },
    "nodeCount": {
      "description": "The number of processors this application should utilize while running. If the application is not of executionType PARALLEL, this should be 1.",
      "type": "integer"
    },
    "notifications": {
      "description": "An array of notifications you wish to receive.",
      "type": "array"
    },
    "parameters": {
      "description": "The application specific parameters needed for this job. These vary from application to application and should be entered as multiple individual parameters in the form. The actual dataType will be determined by the application description.",
      "type": "JobParameters"
    },
    "processorsPerNode": {
      "description": "The number of processors this application should utilize while running. If the application is not of executionType PARALLEL, this should be 1.",
      "type": "integer"
    }
  },
  "required": [
    "inputs",
    "name",
    "parameters",
    "appId",
    "archive"
  ],
  "title": "AgavePy JobRequest schema",
  "type": "object"
}

Response:¶

A single Job object

delete: Deletes a job from the user’s history.¶

jobs.delete(jobId=<JOBID>)

Keyword Args:¶

jobId: The id of the job. (string)

Response:¶

String

get: Get details of the job with the specific job id.¶

jobs.get(jobId=<JOBID>)

Keyword Args:¶

jobId: The id of the job. (string)

Response:¶

A single Job object

manage: Perform an action on a job.¶

jobs.manage(body=<BODY>, jobId=<JOBID>)

Keyword Args:¶

body: The operation to perform. (JSON, JobOperationRequest)

jobId: The id of the job. (string)

Response:¶

A single Job object

getHistory: Get the history of this job.¶

jobs.getHistory(jobId=<JOBID>, limit=250, offset=0)

Keyword Args:¶

jobId: The id of the job. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of JobHistory objects

deletePermissions: Deletes all permissions on an job.¶

jobs.deletePermissions(jobId=<JOBID>)

Keyword Args:¶

jobId: The id of the job. (string)

Response:¶

String

listPermissions: Get the permission ACL for this job.¶

jobs.listPermissions(jobId=<JOBID>, limit=250, offset=0)

Keyword Args:¶

jobId: The id of the job. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of Permission objects

updatePermissions: Add or update a user’s permission for an application.¶

jobs.updatePermissions(body=<BODY>, jobId=<JOBID>)

Keyword Args:¶

body: The permission add or update. (JSON, JobPermissionRequest)

jobId: The id of the job. (string)

Response:¶

String

deletePermissionsForUser: Deletes all permissions for the given user on an job.¶

jobs.deletePermissionsForUser(uniqueName=<UNIQUENAME>, username=<USERNAME>)

Keyword Args:¶

uniqueName: The id of the application. The application id is made up of the name and version separated by a dash. (string)

username: The username of the api user associated with the permission (string)

Response:¶

None

listPermissionsForUser: Get a specific user’s permissions for a job.¶

jobs.listPermissionsForUser(jobId=<JOBID>, limit=250, offset=0, username=<USERNAME>)

Keyword Args:¶

jobId: The id of the job. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

username: The username of the api user associated with the permission. (string)

Response:¶

Array of Permission objects

updatePermissionsForUser: Add or update a user’s permission for an job.¶

jobs.updatePermissionsForUser(body=<BODY>, jobId=<JOBID>, username=<USERNAME>)

Keyword Args:¶

body: The permission to update. (JSON, JobPermissionRequest)

jobId: The id of the job. (string)

username: The username of the api user associated with the permission (string)

Response:¶

String

getStatus: Get the status of the job.¶

jobs.getStatus(jobId=<JOBID>)

Keyword Args:¶

jobId: The id of the job. (string)

Response:¶

A single JobStatus object

listOutputs: List contents of a job’s output directory.¶

jobs.listOutputs(filePath=None, jobId=<JOBID>, limit=250, offset=0)

Keyword Args:¶

filePath: Path to an output file or folder relative to the job output directory. This resource will follow data around as it moves from the execution system to archival storage. (string, optional)

jobId: The id of the job. (string)

limit: max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of RemoteFile objects

downloadOutput: Download an output file from a specific job.¶

jobs.downloadOutput(filePath=<FILEPATH>, jobId=<JOBID>)

Keyword Args:¶

filePath: Path to an output file relative to the job output directory. (string)

jobId: The id of the job. (string)

Response:¶

None

Metadata¶

These functions help you to discover, inspect, share, and manage Tapis metadata documents and document schemas.

meta¶

Summary: Create and manage metadata

addMetadata: Update or Add new Metadata.¶

meta.addMetadata(body=<BODY>)

Keyword Args:¶

body: The metadata to add. (JSON, MetadataRequest)

MetadataRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/MetadataRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "associationIds": {
      "description": "UUIDs of associated Agave entities, including the Data to which this Metadata belongs.",
      "type": "array"
    },
    "name": {
      "description": "The name of this metadata",
      "type": "string"
    },
    "schemaId": {
      "description": "The UUID of the schema that should be used to validate this request.",
      "type": "string"
    },
    "value": {
      "description": "A free text or JSON string containing the metadata stored for the given associationIds",
      "type": "string"
    }
  },
  "required": [
    "name",
    "value"
  ],
  "title": "AgavePy MetadataRequest schema",
  "type": "object"
}

Response:¶

A single Metadata object

listMetadata: List and/or search metadata.¶

meta.listMetadata(limit=250, offset=0, privileged=True, q=None)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

privileged: If false, implicit permissions are ignored and only records to which the user has explicit permissions are returned (boolean, optional)

q: The query to perform. Traditional MongoDB queries are supported (string, optional)

Response:¶

Array of MetadataResponse objects

deleteMetadata: Remove Metadata from the system.¶

meta.deleteMetadata(uuid=<UUID>)

Keyword Args:¶

uuid: The uuid of the metadata item (string)

Response:¶

A single EmptyMetadata object

getMetadata: Retrieve Metadata.¶

meta.getMetadata(limit=250, offset=0, uuid=<UUID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

uuid: The uuid of the metadata item (string)

Response:¶

A single Metadata object

updateMetadata: Update or Add new Metadata.¶

meta.updateMetadata(body=<BODY>, uuid=<UUID>)

Keyword Args:¶

body: The metadata to update. (JSON, MetadataRequest)

uuid: The uuid of the metadata item (string)

Response:¶

A single Metadata object

addSchema: Add a new Metadata Schema.¶

meta.addSchema(body=<BODY>)

Keyword Args:¶

body: A valid JSON Schema object (JSON, string)

Response:¶

A single MetadataSchema object

searchSchema: Retrieve Metadata Schemata.¶

meta.searchSchema(limit=250, offset=0, uuid=<UUID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single MetadataSchema object

deleteSchema: Remove Metadata Schema from the system.¶

meta.deleteSchema(uuid=<UUID>)

Keyword Args:¶

uuid: The uuid of the metadata schema item (string)

Response:¶

A single EmptyMetadata object

getSchema: Retrieve Metadata Schemata.¶

meta.getSchema(limit=250, offset=0, uuid=<UUID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single MetadataSchema object

updateSchema: Update or Add a new Metadata Schema.¶

meta.updateSchema(body=<BODY>, uuid=<UUID>)

Keyword Args:¶

body: A valid JSON Schema object (JSON, string)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single MetadataSchema object

deleteMetadataPermission: Deletes all permissions on the given metadata.¶

meta.deleteMetadataPermission(uuid=<UUID>)

Keyword Args:¶

uuid: The uuid of the metadata item (string)

Response:¶

A single EmptyMetadata object

listMetadataPermissions: Get the permission ACL for this metadata.¶

meta.listMetadataPermissions(limit=250, offset=0, uuid=<UUID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

uuid: The uuid of the metadata item (string)

Response:¶

Array of Permission objects

updateMetadataPermissions: Add or update a user’s permission for the given metadata.¶

meta.updateMetadataPermissions(body=<BODY>, uuid=<UUID>)

Keyword Args:¶

body: The metadata permission to update. (JSON, MetadataPermissionRequest)

uuid: The uuid of the metadata item (string)

Response:¶

A single Permission object

deleteMetadataPermissionsForUser: Deletes all permissions on the given metadata.¶

meta.deleteMetadataPermissionsForUser(username=<USERNAME>, uuid=<UUID>)

Keyword Args:¶

username: The username of the permission owner (string)

uuid: The uuid of the metadata item (string)

Response:¶

A single EmptyMetadata object

listMetadataPermissionsForUser: Get the permission ACL for this metadata.¶

meta.listMetadataPermissionsForUser(username=<USERNAME>, uuid=<UUID>)

Keyword Args:¶

username: The username of the permission owner (string)

uuid: The uuid of the metadata item (string)

Response:¶

A single Permission object

updateMetadataPermissionsForUser: Add or update a user’s permission for the given metadata.¶

meta.updateMetadataPermissionsForUser(body=<BODY>, username=<USERNAME>, uuid=<UUID>)

Keyword Args:¶

body: The metadata permission to update. (JSON, MetadataPermissionRequest)

username: The username of the permission owner (string)

uuid: The uuid of the metadata item (string)

Response:¶

A single Permission object

deleteSchemaPermissions: Deletes all permissions on the given schema.¶

meta.deleteSchemaPermissions(uuid=<UUID>)

Keyword Args:¶

uuid: The uuid of the metadata schema item (string)

Response:¶

A single EmptyMetadata object

listSchemaPermissions: Get the permission ACL for this schema.¶

meta.listSchemaPermissions(limit=250, offset=0, uuid=<UUID>)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

uuid: The uuid of the metadata schema item (string)

Response:¶

Array of Permission objects

updateSchemaPermissions: Add or update a user’s permission for the given schema.¶

meta.updateSchemaPermissions(body=<BODY>, uuid=<UUID>)

Keyword Args:¶

body: The schema permission to update. (JSON, MetadataPermissionRequest)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single Permission object

deleteSchemaPermissionsForUser: Deletes all permissions on the given metadata.¶

meta.deleteSchemaPermissionsForUser(username=<USERNAME>, uuid=<UUID>)

Keyword Args:¶

username: The username of the permission owner (string)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single EmptyMetadata object

listSchemaPermissionsForUser: Get the permission ACL for this schema.¶

meta.listSchemaPermissionsForUser(username=<USERNAME>, uuid=<UUID>)

Keyword Args:¶

username: The username of the permission owner (string)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single Permission object

updateSchemaPermissionsForUser: Add or update a user’s permission for the given metadata schema.¶

meta.updateSchemaPermissionsForUser(body=<BODY>, username=<USERNAME>, uuid=<UUID>)

Keyword Args:¶

body: The schema permission to update. (JSON, MetadataPermissionRequest)

username: The username of the permission owner (string)

uuid: The uuid of the metadata schema item (string)

Response:¶

A single Permission object

Notifications¶

These functions help you to discover, inspect, subscribe to, and manage Tapis notifications and events.

notifications¶

Summary: Subscribe to and manage notifications

add: Update or Add new notification.¶

notifications.add(body=<BODY>)

Keyword Args:¶

body: The notification to add. (JSON, NotificationRequest)

NotificationRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/NotificationRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "associatedUuid": {
      "description": "UUID of resource to whome the event applies.",
      "type": "string"
    },
    "persistent": {
      "description": "Whether this notification should stay active after it fires the first time.",
      "type": "boolean"
    },
    "url": {
      "description": "The url or email address that will be notified of the event.",
      "type": "string"
    }
  },
  "required": [
    "url",
    "associatedUuid",
    "persistent"
  ],
  "title": "AgavePy NotificationRequest schema",
  "type": "object"
}

Response:¶

A single Notification object

list: Retrieve notification for a specific resource.¶

notifications.list(associatedUuid=None, limit=250, offset=0)

Keyword Args:¶

associatedUuid: The uuid of the associated resource. All notifications for this resource visible to the user will be returned. (string, optional)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of Notification objects

delete: Remove notification from the system.¶

notifications.delete(uuid=<UUID>)

Keyword Args:¶

uuid: The uuid of the notification item (string)

Response:¶

A single EmptyNotification object

get: Retrieve notification.¶

notifications.get(uuid=<UUID>)

Keyword Args:¶

uuid: The uuid of the notification item (string)

Response:¶

A single Notification object

update: Update or Add new notification.¶

notifications.update(body=<BODY>, uuid=<UUID>)

Keyword Args:¶

body: The notification to update. (JSON, NotificationRequest)

uuid: The uuid of the notification item (string)

Response:¶

A single Notification object

Postits¶

These functions help you to discover, inspect, and manage Tapis post-its.

postits¶

Summary: Create pre-authenticated, disposable URLs

create: Create a new PostIt¶

postits.create(body=<BODY>)

Keyword Args:¶

body: The PostIt to create. (JSON, PostItRequest)

PostItRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/PostItRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "internalUsername": {
      "description": "The username of the internal user attached to this PostIt.",
      "type": "string"
    },
    "lifetime": {
      "description": "The maximum lifetime in seconds of this PostIt on this token. Defaults to 2592000 (30 days)",
      "type": "integer"
    },
    "maxUses": {
      "description": "The maximum number of invocations remaining on this PostIt. Defaults to no limit",
      "type": "integer"
    },
    "method": {
      "description": "The method that will be invoked when the PostIt is redeemed.",
      "enum": [
        "GET",
        "PUT",
        "POST",
        "DELETE"
      ],
      "type": "string"
    },
    "noauth": {
      "description": "If true, the provided url will be called without authentication. Default is false",
      "type": "boolean"
    },
    "url": {
      "description": "The url that will be invoked when the PostIt is redeemed.",
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "title": "AgavePy PostItRequest schema",
  "type": "object"
}

Response:¶

None

list: List existing PostIts¶

postits.list(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of PostIt objects

delete: Immediately invalidates this PostIt URL.¶

postits.delete(nonce=<NONCE>)

Keyword Args:¶

nonce: The nonce of this PostIt URL (string)

Response:¶

A single PostIt object

Profiles¶

These functions help you to discover, inspect, and (in some cases) manage user profiles on a Tapis tenant.

profiles¶

Summary: Create and manage application users

create: Create new user profile¶

profiles.create(body=<BODY>)

Keyword Args:¶

body: The profile information for a new user (JSON, string)

Response:¶

A single Profile object

list: List user profiles¶

profiles.list(email=None, first_name=None, full_name=None, last_name=None, limit=250, name=None, offset=0, status=None, username=None)

Keyword Args:¶

email: Filter results by email. (string, optional)

first_name: Filter results by first_name. (string, optional)

full_name: Filter results by full_name. (string, optional)

last_name: Filter results by last_name. (string, optional)

limit: The max number of results. (integer, optional)

name: Filter results by name. (string, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

status: Filter results by status. (string, optional)

username: Filter results by username. (string, optional)

Response:¶

Array of Profile objects

get: Find authenticated user profile¶

profiles.get()

Response:¶

A single Profile object

delete: Delete user profile¶

profiles.delete(username=<USERNAME>)

Keyword Args:¶

username: The username of a valid api user (string)

Response:¶

A single Profile object

listByUsername: Find api user profile by their api username¶

profiles.listByUsername(username=<USERNAME>)

Keyword Args:¶

username: The username of a valid api user (string)

Response:¶

A single Profile object

update: Update user profile¶

profiles.update(body=<BODY>, username=<USERNAME>)

Keyword Args:¶

body: Updated profile information for a user (JSON, string)

username: The username of a valid api user (string)

Response:¶

A single Profile object

Actors¶

Abaco is a Tapis web service providing functions-as-a-service (FaaS) to the research computing community. It implements functions using the Actor Model of concurrent computation, so the relevant API name in Tapis is actors.

In Abaco, each actor is associated with a Docker image, and actor containers are executed in response to messages posted to their inbox, which itself is given by a URI exposed over HTTP. Use cases for Abaco actors include moving data, running Tapis apps, interacting with other actors, and interoperating with third-party web services.

The functions documented here help you to discover, inspect, manage, and use Abaco actors.

actors¶

Summary: Create and manage actors.

add: Register an actor.¶

actors.add(body=<BODY>)

Keyword Args:¶

body: The description of the actor to add. (JSON, Actor)

Actor schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/Actor.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "defaultEnvironment": {
      "description": "Default environmental variables and values.",
      "type": "dict"
    },
    "description": {
      "description": "Description of this actor.",
      "type": "string"
    },
    "id": {
      "description": "The unique id of the actor.",
      "type": "string"
    },
    "image": {
      "description": "Docker image associated with the actor.",
      "type": "string"
    },
    "owner": {
      "description": "username of the owner of the actor.",
      "type": "string"
    },
    "privileged": {
      "description": "Whether this actor runs in privileged mode.",
      "type": "boolean"
    },
    "stateless": {
      "description": "Whether the actor stores private state.",
      "type": "boolean"
    },
    "status": {
      "description": "Current status of the actor.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy Actor schema",
  "type": "object"
}

Response:¶

A single Actor object

list: List actors¶

actors.list(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of Actor objects

delete: Delete a specific actor.¶

actors.delete(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

A single String object

get: Retrieve details about a specific actor.¶

actors.get(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

A single Actor object

update: Retrieve details about a specific actor.¶

actors.update(actorId=<ACTORID>, body=<BODY>)

Keyword Args:¶

actorId: The id of the actor. (string)

body: The description of the actor to update. (JSON, Actor)

Actor schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/Actor.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "defaultEnvironment": {
      "description": "Default environmental variables and values.",
      "type": "dict"
    },
    "description": {
      "description": "Description of this actor.",
      "type": "string"
    },
    "id": {
      "description": "The unique id of the actor.",
      "type": "string"
    },
    "image": {
      "description": "Docker image associated with the actor.",
      "type": "string"
    },
    "owner": {
      "description": "username of the owner of the actor.",
      "type": "string"
    },
    "privileged": {
      "description": "Whether this actor runs in privileged mode.",
      "type": "boolean"
    },
    "stateless": {
      "description": "Whether the actor stores private state.",
      "type": "boolean"
    },
    "status": {
      "description": "Current status of the actor.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy Actor schema",
  "type": "object"
}

Response:¶

A single Actor object

deleteMessages: Delete messages from an actor¶

actors.deleteMessages(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

None

getMessages: Get the current number of messages for an actor.¶

actors.getMessages(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

A single ActorMessages object

sendBinaryMessage: Send a message to an actor mailbox.¶

actors.sendBinaryMessage(actorId=<ACTORID>, environment=None, message=<MESSAGE>)

Keyword Args:¶

actorId: The id of the actor. (string)

environment: Optional dictionary of environmental variables (dict, optional)

message: The description of the message to add. (JSON, MessageRequest)

MessageRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/MessageRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "message": {
      "description": "The message to send to the actor.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy MessageRequest schema",
  "type": "object"
}

Response:¶

A single ActorMessageResponse object

sendMessage: Send a message to an actor mailbox.¶

actors.sendMessage(actorId=<ACTORID>, body=<BODY>, environment=None)

Keyword Args:¶

actorId: The id of the actor. (string)

body: The description of the message to add. (JSON, MessageRequest)

environment: Optional dictionary of environmental variables (dict, optional)

Response:¶

A single ActorMessageResponse object

getState: Get the current state for an actor.¶

actors.getState(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

A single ActorState object

updateState: Update an actor’s state with a JSON-serializable object.¶

actors.updateState(actorId=<ACTORID>, body=<BODY>)

Keyword Args:¶

actorId: The id of the actor. (string)

body: The value of the state. Should be JSON-serializable. (JSON, string)

Response:¶

A single ActorState object

getPermissions: Get the current permissions for an actor.¶

actors.getPermissions(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

A single ActorPermissions object

updatePermissions: Update an actor’s permissions with a new permission for a user.¶

actors.updatePermissions(actorId=<ACTORID>, body=<BODY>)

Keyword Args:¶

actorId: The id of the actor. (string)

body: The permission record; user and level fields required. (JSON, PermissionsUpdateRequest)

PermissionsUpdateRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/PermissionsUpdateRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "level": {
      "description": "The level associated with the permission.",
      "type": "string"
    },
    "user": {
      "description": "The user associated with the permission.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy PermissionsUpdateRequest schema",
  "type": "object"
}

Response:¶

A single ActorPermissionsResponse object

addWorker: Add a worker to an actor.¶

actors.addWorker(actorId=<ACTORID>, body=<BODY>)

Keyword Args:¶

actorId: The id of the actor. (string)

body: The description of the workers to add. (JSON, AddWorkersRequest)

AddWorkersRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/AddWorkersRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "num": {
      "description": "The number of workers to ensure are running.",
      "type": "int"
    }
  },
  "required": [],
  "title": "AgavePy AddWorkersRequest schema",
  "type": "object"
}

Response:¶

A single EmptyActorWorkerRequestResponse object

listWorkers: List the current workers for an actor.¶

actors.listWorkers(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

Array of ActorWorker objects

deleteWorker: Delete a worker.¶

actors.deleteWorker(actorId=<ACTORID>, workerId=<WORKERID>)

Keyword Args:¶

actorId: The id of the actor. (string)

workerId: The id of the worker. (string)

Response:¶

A single String object

getWorker: Get the details about a specific worker for an actor.¶

actors.getWorker(actorId=<ACTORID>, workerId=<WORKERID>)

Keyword Args:¶

actorId: The id of the actor. (string)

workerId: The id of the worker. (string)

Response:¶

A single ActorWorker object

addNonce: Add a nonce to an actor.¶

actors.addNonce(actorId=<ACTORID>, body=)

Keyword Args:¶

actorId: The id of the actor. (string)

body: The description of the nonce to add. (JSON, AddNonceRequest, optional)

AddNonceRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/AddNonceRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "level": {
      "description": "Permissions level associated with this nonce (default is EXECUTE).",
      "type": "string"
    },
    "maxUses": {
      "description": "Max number of times nonce can be redeemed.",
      "type": "int"
    }
  },
  "required": [],
  "title": "AgavePy AddNonceRequest schema",
  "type": "object"
}

Response:¶

A single EmptyActorNonceRequestResponse object

listNonces: List the current nonces for an actor.¶

actors.listNonces(actorId=<ACTORID>)

Keyword Args:¶

actorId: The id of the actor. (string)

Response:¶

Array of ActorNonce objects

deleteNonce: Delete a nonce.¶

actors.deleteNonce(actorId=<ACTORID>, nonceId=<NONCEID>)

Keyword Args:¶

actorId: The id of the actor. (string)

nonceId: The id of the nonce. (string)

Response:¶

A single String object

getNonce: Get the details about a specific nonce for an actor.¶

actors.getNonce(actorId=<ACTORID>, nonceId=<NONCEID>)

Keyword Args:¶

actorId: The id of the actor. (string)

nonceId: The id of the nonce. (string)

Response:¶

A single ActorNonce object

addAlias: Add an alias of an actor.¶

actors.addAlias(body=)

Keyword Args:¶

body: The description of the alias to add. (JSON, AddAliasRequest, optional)

AddAliasRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/AddAliasRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "actorId": {
      "description": "The id of the actor to associate with this alias.",
      "type": "string"
    },
    "alias": {
      "description": "The alias to create.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy AddAliasRequest schema",
  "type": "object"
}

Response:¶

A single ActorAlias object

listAliases: List all current aliases¶

actors.listAliases()

AddAliasRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/AddAliasRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "actorId": {
      "description": "The id of the actor to associate with this alias.",
      "type": "string"
    },
    "alias": {
      "description": "The alias to create.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy AddAliasRequest schema",
  "type": "object"
}

Response:¶

Array of ActorAlias objects

deleteAlias: Delete an alias.¶

actors.deleteAlias(alias=<ALIAS>)

Keyword Args:¶

alias: The id of the alias. (string)

Response:¶

A single String object

getAlias: Get the details of a specific alias.¶

actors.getAlias(alias=<ALIAS>)

Keyword Args:¶

alias: The id of the alias. (string)

Response:¶

A single ActorAlias object

listExecutions: Summary data of all actor executions.¶

actors.listExecutions(actorId=<ACTORID>, limit=250, offset=0)

Keyword Args:¶

actorId: The id of the actor. (string)

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

A single ExecutionsSummary object

getExecution: Retrieve details about a specific actor execution.¶

actors.getExecution(actorId=<ACTORID>, executionId=<EXECUTIONID>)

Keyword Args:¶

actorId: The id of the actor. (string)

executionId: The id of the execution. (string)

Response:¶

A single Execution object

getOneExecutionResult: Get result for a specific actor execution.¶

actors.getOneExecutionResult(actorId=<ACTORID>, executionId=<EXECUTIONID>)

Keyword Args:¶

actorId: The id of the actor. (string)

executionId: The id of the execution. (string)

Response:¶

None

getExecutionLogs: Get logs for a specific actor execution.¶

actors.getExecutionLogs(actorId=<ACTORID>, executionId=<EXECUTIONID>)

Keyword Args:¶

actorId: The id of the actor. (string)

executionId: The id of the execution. (string)

Response:¶

A single ExecutionLogs object

Search¶

Tapis resources can be queried to search for items using parameters. Every resource list operation can be passed a dictionary of search terms and values using the query argument. For example, you may search Jobs submissions for a specific appId using the following code:

Agave.jobs.list(query={"appId.like", "*matlab*"})

Additional detail on Tapis search is available from the Tapis API documentation.

Admin¶

These functions help you to discover, inspect, and manage custom APIs on a specific Tapis tenant. They generally require special administrative access to use.

admin¶

Summary: Tenant admin services.

addAccount: Register a service account.¶

admin.addAccount(body=<BODY>)

Keyword Args:¶

body: The description of the service account to add. (JSON, ServiceAccount)

ServiceAccount schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ServiceAccount.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "id": {
      "description": "The unique id of the service account.",
      "type": "string"
    },
    "password": {
      "description": "The password for the service account.",
      "type": "string"
    },
    "roles": {
      "description": "roles occupied by service account.",
      "type": "array"
    }
  },
  "required": [],
  "title": "AgavePy ServiceAccount schema",
  "type": "object"
}

Response:¶

A single ServiceAccount object

listAccounts: List service accounts¶

admin.listAccounts(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of ServiceAccountSummary objects

deleteAccount: Delete a specific service account.¶

admin.deleteAccount(accountId=<ACCOUNTID>)

Keyword Args:¶

accountId: The id of the service account. (string)

Response:¶

A single String object

getAccount: Retrieve details about a specific service account.¶

admin.getAccount(accountId=<ACCOUNTID>)

Keyword Args:¶

accountId: The id of the service account. (string)

Response:¶

A single ServiceAccount object

updateAccount: Update a specific service account.¶

admin.updateAccount(accountId=<ACCOUNTID>, body=<BODY>)

Keyword Args:¶

accountId: The id of the service account. (string)

body: The description of the service account to update. (JSON, ServiceAccount)

ServiceAccount schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ServiceAccount.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "id": {
      "description": "The unique id of the service account.",
      "type": "string"
    },
    "password": {
      "description": "The password for the service account.",
      "type": "string"
    },
    "roles": {
      "description": "roles occupied by service account.",
      "type": "array"
    }
  },
  "required": [],
  "title": "AgavePy ServiceAccount schema",
  "type": "object"
}

Response:¶

A single ServiceAccount object

addRoleToAccount: Add a role to a service account.¶

admin.addRoleToAccount(accountId=<ACCOUNTID>, body=<BODY>)

Keyword Args:¶

accountId: The id of the service account. (string)

body: The description of the role to add. (JSON, AddRoleToAccountRequest)

AddRoleToAccountRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/AddRoleToAccountRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "role_id": {
      "description": "The id of the role to add to the service account.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy AddRoleToAccountRequest schema",
  "type": "object"
}

Response:¶

A single ServiceAccount object

listAccountRoles: List the roles occupied by a service account.¶

admin.listAccountRoles(accountId=<ACCOUNTID>)

Keyword Args:¶

accountId: The id of the service account. (string)

Response:¶

A single ServiceAccount object

deleteRoleFromAccount: Delete a role from the list of occupied roles of a service account.¶

admin.deleteRoleFromAccount(accountId=<ACCOUNTID>, roleId=<ROLEID>)

Keyword Args:¶

accountId: The id of the service account. (string)

roleId: The id of the role. (string)

Response:¶

A single String object

addRole: Register a service role.¶

admin.addRole(body=<BODY>)

Keyword Args:¶

body: The description of the service role to add. (JSON, Role)

Role schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/Role.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "id": {
      "description": "The unique id of the role.",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy Role schema",
  "type": "object"
}

Response:¶

A single RoleDetails object

listRoles: List service roles.¶

admin.listRoles(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of RoleSummary objects

deleteRole: Delete a specific service role.¶

admin.deleteRole(roleId=<ROLEID>)

Keyword Args:¶

roleId: The id of the service role. (string)

Response:¶

A single String object

getRole: Retrieve details about a specific service role.¶

admin.getRole(roleId=<ROLEID>)

Keyword Args:¶

roleId: The id of the service role. (string)

Response:¶

A single RoleDetails object

addAccountToRole: Add a service account to a role.¶

admin.addAccountToRole(body=<BODY>, roleId=<ROLEID>)

Keyword Args:¶

body: The description of the service account to add. (JSON, AddServiceAccountToRoleRequest)

roleId: The id of the service role. (string)

Response:¶

A single RoleDetails object

listAccountsInRole: Get the service accounts that occupy a service role.¶

admin.listAccountsInRole(roleId=<ROLEID>)

Keyword Args:¶

roleId: The id of the service role. (string)

Response:¶

A single RoleDetails object

deleteAccountFromRole: Delete a service from the list of accounts occupying a service role.¶

admin.deleteAccountFromRole(accountId=<ACCOUNTID>, roleId=<ROLEID>)

Keyword Args:¶

accountId: The id of the service account. (string)

roleId: The id of the service role. (string)

Response:¶

A single String object

listClients: List clients.¶

admin.listClients(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of Client objects

addApi: Register an API.¶

admin.addApi(body=<BODY>)

Keyword Args:¶

body: The description of the API to add. (JSON, ApiRequestBody)

ApiRequestBody schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ApiRequestBody.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "api_name": {
      "description": "Name of the API, which will also be used to identify the API.",
      "type": "string"
    },
    "auth": {
      "description": "List of quth type per method from (none, oauth). Can also be single string for all methods.",
      "type": "array"
    },
    "context": {
      "description": "Root path (context) for the API, starting with a slash character.",
      "type": "string"
    },
    "methods": {
      "description": "List of allowed methods from (GET, POST, PUT, DELETE, HEAD).",
      "type": "array"
    },
    "roles": {
      "description": "List of required roles to subscribe to API (required when visibility is 'restricted')",
      "type": "array"
    },
    "url": {
      "description": "Fully qualified production URL for the backend service (should include http or https).",
      "type": "string"
    },
    "visibility": {
      "description": "Optionally set the visibility to 'public' or 'restricted' (default is public).",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy ApiRequestBody schema",
  "type": "object"
}

Response:¶

A single Api object

listApis: List APIs.¶

admin.listApis(limit=250, offset=0)

Keyword Args:¶

limit: The max number of results. (integer, optional)

offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer, optional)

Response:¶

Array of ApiSummary objects

deleteApi: Delete a specific API.¶

admin.deleteApi(apiId=<APIID>)

Keyword Args:¶

apiId: The id of the API. (string)

Response:¶

A single String object

getApi: Retrieve details about a specific API.¶

admin.getApi(apiId=<APIID>)

Keyword Args:¶

apiId: The id of the API. (string)

Response:¶

A single Api object

updateApiStatus: Update a specific API.¶

admin.updateApiStatus(apiId=<APIID>, body=<BODY>)

Keyword Args:¶

apiId: The id of the API. (string)

body: The new status for the API. (JSON, ApiStatus)

ApiStatus schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ApiStatus.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "status": {
      "description": "Status of the API: one of (CREATED, PUBLISHED, RETIRED).",
      "type": "string"
    }
  },
  "required": [],
  "title": "AgavePy ApiStatus schema",
  "type": "object"
}

Response:¶

A single Api object

Clients¶

These functions help you to discover, inspect, and manage Tapis Oauth2 API clients.

clients¶

Summary: Create and manage API keys. Requires HTTP BASIC authentication

create: Create a new client¶

clients.create(body=<BODY>)

Keyword Args:¶

body: The api client to create (JSON, ClientRequest)

ClientRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ClientRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "callbackUrl": {
      "description": "Callback URL for OAuth authentication grant.",
      "type": "string"
    },
    "description": {
      "description": "Description of the client. This will be shown to users when authentication via OAuth web flows",
      "type": "string"
    },
    "name": {
      "description": "The name of the client.",
      "type": "string"
    },
    "tier": {
      "description": "The access tier for this client.",
      "enum": [
        "UNLIMITED",
        "GOLD",
        "SILVER",
        "BRONZE"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "AgavePy ClientRequest schema",
  "type": "object"
}

Response:¶

A single Client object

list: List existing clients¶

clients.list()

ClientRequest schema

{
  "$id": "http://agavepy.readthedocs.io/en/latest/ClientRequest.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "callbackUrl": {
      "description": "Callback URL for OAuth authentication grant.",
      "type": "string"
    },
    "description": {
      "description": "Description of the client. This will be shown to users when authentication via OAuth web flows",
      "type": "string"
    },
    "name": {
      "description": "The name of the client.",
      "type": "string"
    },
    "tier": {
      "description": "The access tier for this client.",
      "enum": [
        "UNLIMITED",
        "GOLD",
        "SILVER",
        "BRONZE"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "AgavePy ClientRequest schema",
  "type": "object"
}

Response:¶

Array of Client objects

delete: Immediately deletes this client and renders the API keys useless.¶

clients.delete(clientName=<CLIENTNAME>)

Keyword Args:¶

clientName: The name of the client to be deleted (string)

Response:¶

A single String object

getClientByName: Returns a detailed description of a named client.¶

clients.getClientByName(clientName=<CLIENTNAME>)

Keyword Args:¶

clientName: The name of the client to be deleted (string)

Response:¶

Array of Client objects

addSubscriptionForClient: Lists all APIs to which the client is subscribed¶

clients.addSubscriptionForClient(body=<BODY>, clientName=<CLIENTNAME>)

Keyword Args:¶

body: The api client to create (JSON, ClientSubscriptionRequest)

clientName: The name of the client to be subscribe to this api (string)

Response:¶

A single Subscription object

deleteSubscriptionsForClient: Unsubscribe the client from all APIs¶

clients.deleteSubscriptionsForClient(clientName=<CLIENTNAME>)

Keyword Args:¶

clientName: The name of the client to be deleted (string)

Response:¶

A single String object

listSubscriptionsForClient: Lists all APIs to which the client is subscribed¶

clients.listSubscriptionsForClient(clientName=<CLIENTNAME>)

Keyword Args:¶

clientName: The name of the client to be deleted (string)

Response:¶

Array of Subscription objects

AgavePy Documentation¶

About Tapis¶

Example: List contents of a Tapis storageSystem path¶

Installing AgavePy¶

From source¶

Obtain the source code from GitHub¶

Install with setuptools¶

Install with GNU make¶

Tapis User Account¶

Other Tenants¶

Authenticating with Tapis¶

Oauth2 Overview¶

Create a Client¶

Generate an Access Token¶

Refreshing the Token¶

Local Credential Cache¶

Special Cases¶

Access-Only Client¶

Environment Variables¶

The AgavePy client¶

Specifying Parameters¶

Pagination Options¶

Reponses from AgavePy¶

Interpreting Errors¶

Systems¶

systems¶

add: Add or update a system.¶

list: Show all systems available to the user.¶

delete: Delete a system.¶

get: Find information about an individual system.¶

manage: Perform a management action on the system.¶

update: Find information about an individual system.¶

deleteRoles: Deletes all roles on a system.¶

listRoles: Get a list of all users and their roles on this system.¶

updateRole: Add or update a user’s role on a system.¶

deleteRoleForUser: Deletes all roles on a system.¶

getRoleForUser: Get a specific user’s roles on this system.¶

updateRoleForUser: Add or update a user’s role on a system.¶

deleteCredentials: Deletes all credentials registered to a system.¶

deleteCredentialsForInternalUser: Deletes all credentials registered to a system.¶

Files¶

files¶

deleteFromDefaultSystem: Deletes a file or folder.¶

downloadFromDefaultSystem: Download a file from the user’s default storage location.¶

importToDefaultSystem: Import a file via direct upload or importing from a url to the user’s default storage location.¶

manageOnDefaultSystem: Perform an action on a file or folder.¶

delete: Deletes a file or folder.¶

download: Download a file from the user’s default storage location.¶

importData: Import a file via direct upload or importing from a url to the user’s default storage location.¶

manage: Perform an action on a file or folder.¶

listOnDefaultSystem: Get a remote directory listing.¶

list: Get a remote directory listing on a specific system.¶

getHistoryOnDefaultSystem: Download a file from the user’s default storage location.¶

getHistory: Return history of api actions.¶

listPermissionsOnDefaultSystem: List all the share permissions for a file or folder.¶

updatePermissionsOnDefaultSystem: Update permissions for a single user.¶

deletePermissions: Deletes all permissions on a file except those of the owner.¶

listPermissions: List all the share permissions for a file or folder.¶

updatePermissions: Update permissions for a single user.¶

Apps¶

apps¶

add: Register and update new applications.¶

list: Get a list of available applications.¶

delete: Deletes an application.¶

get: Get details of an application by it’s unique id.¶

manage: Edit an application.¶

update: Update an application.¶

deletePermissions: Deletes all permissions on an application.¶

listPermissions: Get the permission ACL for this application.¶

updateApplicationPermissions: Add or update a user’s permission for an application.¶

deletePermissionsForUser: Deletes all permissions for the given user on an application.¶

listPermissionsForUser: Get a specific user’s permissions for an application.¶

updatePermissionsForUser: Add or update a user’s permission for an application.¶

listByName: Get a list of applications with the given name.¶

listBySystemId: Get a list of applications with the given systemId as their executionHost.¶

Jobs¶

jobs¶

list: Get a list of jobs the authenticated user had submitted.¶

submit: Submit a new job request.¶

delete: Deletes a job from the user’s history.¶