AgavePy documentation¶
About AgavePy¶
AgavePy is a client that will allow you to script your interaction with the Agave API. AgavePy is also the engine powering TACC/Cloud/agave-cli.
Installation Guide¶
Introductory installation guide.
Installation Guide¶
Topics
What will be installed¶
In this guide we will cover how to get AgavePy into your machine.
We will cover how to install the latest official release.
Also, we will cover how to install the latest from the development branch in
case you want to get the latest features and help the TACC team build the most
useful and performant software that meets your needs.
What version to install¶
AgavePy is under constant development.
Some features may be missing from oficial releases but in general oficial
releases are pushed when the project has reached a stable state.
Latest stable release from PiPy¶
You can install the latest official releases.
pip install agavepy
For a specific version:
pip install agavepy==0.73
Latest stable release from source¶
You can also install the latest releases from source, either from the master or from the develop branch.
You will need to first obtain the source code.
To get a copy of the AgavePy repository do:
git clone https://github.com/TACC/agavepy
Once you have cloned the repository, go into it and choose the branch you want
to install.
If you want to install the development version, you can checkout the
develop branch as follows:
git checkout develop
If you have GNU make
installed in your system, you can install AgavePy for Python 3 as follows:
make install
To install AgavePy for Python 2,
make install-py2
The Makefile uses the setup.py file for all installation related logic.
Contributing Guide¶
Contributing guide.
Contributing Guide¶
Reporting bugs and asking for features¶
If you come accross a problem, the package advertises a thing and it does another, it fails without clear reason of what happened, or there is some functionality you believe should be implemented please file an issue on our repository.
Getting involved¶
If you are interested in joining the AgavePy development team you can find
more information in our contributing guide.
Authentication¶
In order to use AgavePy a user or program needs to be authenticated with
the API.
The Agave services use the Oauth protocol to manage user authentication.
The authentication process involves specifying the tenant one wishes to interact with, the creation of an Oauth client that will create and refresh access tokens for the rest of the Agave services, and the request for the creation of an access token and refresh token pair or the use of a refresh token to obtain a new token pair after the tokens have expired. We will refer to the specfication fo a tenant, client configurations, and tokens as a session.
In this section we descrie how AgavePy enables us to go through the process
of initiating and managing a session.
Initiating a Session¶
To work with the Agave API, AgavePy implements the agavepy.agave.Agave
object.
The first step for a user to authenticate with the Agave API is to specify the
which tenant to interact with.
Whenever the user makes a request to the Agave api, Agave will require the
tenant’s base url to make the request.
In order for the user to refer to this tenant in the future in a more
human-friendly way, the Agave object also makes available the tenant id.
Specifying a tenant interactively¶
AgavePy provides two ways for a user to initiate a session.
The first approaches requires the user to specify the tenant information - its
ID and/or the the base url for it - and use the method init from Agave.
The init method will make sure that the tenant_id and api_server
variables are set.
To see all available tenants and chose one to interact with, one can do the following:
>>> from agavepy.agave import Agave
>>> agave = Agave()
>>> agave.init()
ID NAME URL
3dem 3dem Tenant https://api.3dem.org/
agave.prod Agave Public Tenant https://public.agaveapi.co/
araport.org Araport https://api.araport.org/
designsafe DesignSafe https://agave.designsafe-ci.org/
iplantc.org CyVerse Science APIs https://agave.iplantc.org/
irec iReceptor https://irec.tenants.prod.tacc.cloud/
portals Portals Tenant https://portals-api.tacc.utexas.edu/
sd2e SD2E Tenant https://api.sd2e.org/
sgci Science Gateways Community Institute https://sgci.tacc.cloud/
tacc.prod TACC https://api.tacc.utexas.edu/
vdjserver.org VDJ Server https://vdj-agave-api.tacc.utexas.edu/
Please specify the ID for the tenant you wish to interact with: sd2e
>>> agave.tenant_id, agave.api_server
('sd2e', 'https://api.sd2e.org')
If you already know the tenant id you can specify it at the moment you
instantiate the Agave object.
>>> agave = Agave(tenant_id="sd2e")
>>> agave.init()
>>> agave.tenant_id, agave.api_server
('sd2e', 'https://api.sd2e.org')
Similarly, if you know the base url for the tenant.
>>> agave = Agave(api_server="https://api.sd2e.org/")
>>> agave.init()
>>> agave.tenant_id, agave.api_server
('sd2e', 'https://api.sd2e.org/')
Using an existing session¶
The second authentication approach that you can follow is to load a previous
session that has been saved to a configurations file using the method
load_configs.
If you already created an oauth client and have a pair of access and refresh
tokens then you can save this session by using the method save_configs.
To reuse it, simply instantiate an Agave object use the method
load_configs to use an existing session.
>>> from agavepy.agave import Agave
>>> agave = Agave()
>>> agave.load_configs()
>>> agave.tenant_id, agave.api_server
('sd2e', 'https://api.sd2e.org/')
load_configs takes four optional arguments:
cache_dirdirectory to store configurations in (it defaults to~/.agave)tenant_idtenant id of the session to restoreusernameusername for the session to restoreclient_namename of oauth client for the session to restore
OAuth Clients¶
Creating a client¶
Once you have specified the tenant you wish to interact with Initiating a Session we can go ahead and create an oauth client, which in turn we will use to obtain and refresh tokens.
To create a client use the method clients_create.
This method takes two arguments, the client’s name and a description, both
strings.
>>> from agavepy.agave import Agave
>>> ag = Agave(tenant_id="sd2e")
>>> ag.init()
>>> agave.clients_create("my_super_cool_client", "my client's desciption")
API username: your-username
API password:
>>> agave.api_key, agave.api_secret
('some-weird-looking-string', 'of-characters-that-agave-needs')
We will need the api_key and api_secret down the road to generate
access tokens.
Listing all clients¶
To list all agave oauth clients registered for a given user, one can use the clients_list() method.
>>> ag.clients_list()
API username: your-username
API password:
NAME DESCRIPTION
client-name some description
>>>
Deleting a client¶
If you want to delete an oauth client, you can do as such:
>>> ag.clients_delete("some-client-name")
API password:
If you don’t pass a client name to clients_delete, then the Agave
object will try to delete the oauth client in its current session.
Subscribing to an API¶
To subscribe to a TACC api you need to know the api name, the
api version, and the api provider.
If you want to subscribe an oauth client to a TACC api, then you can do so as
follows:
>>> ag.clients_subscribe("PublicKeys", "v2", "admin", client_name="client")
You can also specify the optional function argument client_name. This
should be a string and can be used to subscribe an oauth client not in the
current session.
List client subscriptions¶
To list client subscriptions you can use the clients_subscriptions method:
>>> ag.clients_subscribtions()
API password:
NAME VERSION PROVIDER
Apps v2 admin
Files v2 admin
Jobs v2 admin
Meta v2 admin
Monitors v2 admin
Notifications v2 admin
Postits v2 admin
Profiles v2 admin
Systems v2 admin
Transforms v2 admin
PublicKeys v2 admin
Like clients_subscribe, you can optionally specify the client_name
argument to list the subscriptions for another existing oauth client that you
own.
Access Tokens¶
Getting an access token¶
Now that you have a tenant to interact with, Initiating a Session, and you have
created an oauth client, OAuth Clients, creating an access and refresh tokens
is one method away: get_access_token.
>>> agave.get_access_token()
API password:
>>> agave.token, agave.refresh_token
('imageine-an-access-token-here', 'and-a-refresh-token-here')
Refreshing an access token¶
You can use the refresh_tokens method to manually refresh your tokens.
>>> agave.refresh_tokens()
>>> agave.token, agave.refresh_token
('new-access-token-goes-here', 'new-refresh-token')
Saving your sesssion¶
If you are here, hopefully you were able to specify a tenant, Initiating a Session, create an oauth client, OAuth Clients, and get an access token Access Tokens.
To store your session, you can use save_configs.
>>> agave.save_configs()
save_configs takes an optional argument, cache_dir which tells
Agave the directory where you want to store your configurations otherwise
it will default to ~/.agave.
save_configs will store your configurations in a file named
config.json.
If you use default parameters, this file will be in ~/.agave/config.json.
save_configs also writes a current file for backward-compatibility with
other Agave tools.
The configuration file will look something like this:
{
"current": {
"my_super_cool_client": {
"tenantid": "sd2e",
"baseurl": "https://api.sd2e.org",
"devurl": "",
"apisecret": "some-secret",
"apikey": "some-key",
"username": "your-username",
"access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"created_at": "1539708516",
"expires_in": 14400,
"expires_at": "Tue Oct 16 20:48:36 UTC 2018"
}
},
"sessions": {
"sd2e": {
"your-username": {
"my_super_cool_client": {
"tenantid": "sd2e",
"baseurl": "https://api.sd2e.org/",
"devurl": "",
"apisecret": "some-secret",
"apikey": "some-key",
"username": "your-username",
"access_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"created_at": "1539706810",
"expires_in": 14400,
"expires_at": "Tue Oct 16 20:20:10 UTC 2018"
}
}
}
}
}
Systems¶
Register and manage systems.
Systems¶
Summary: Register and manage systems
add: Add or update a system.¶
agavepy.systems.add(body)
Parameters:¶
- 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",
"scheduler",
"name",
"queues",
"storage",
"executionType",
"login",
"type"
],
"title": "AgavePy SystemRequest schema",
"type": "object"
}
Response:¶
- A single System object
System schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/System.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"default": {
"description": "Is the system the default for the authenticated user?",
"type": "boolean"
},
"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"
},
"lastModified": {
"description": "The date this system was last modified in ISO 8601 format.",
"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"
},
"public": {
"description": "Is the system publicly available?",
"type": "boolean"
},
"queues": {
"description": "The execution paradigm used to run jobs on this system.",
"type": "array"
},
"revision": {
"description": "The number of times this app has been updated.",
"type": "int"
},
"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"
},
"uuid": {
"description": "The uuid of this system.",
"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": [],
"title": "AgavePy System schema",
"type": "object"
}
list: Show all systems available to the user.¶
agavepy.systems.list(default=None, limit=250, offset=0, public=None, type=None)
Parameters:¶
- type: The type of system to return (string)
- default: Should only default systems be returned (boolean)
- public: Should only publicly available systems be returned (boolean)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of SystemSummary objects
SystemSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/SystemSummary.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"default": {
"description": "Is the system the default for the authenticated user?",
"type": "boolean"
},
"description": {
"description": "Verbose description of this system.",
"type": "string"
},
"id": {
"description": "Unique identifier for this system.",
"type": "string"
},
"name": {
"description": "Common name for this system.",
"type": "string"
},
"public": {
"description": "Is the system publicly available?",
"type": "boolean"
},
"status": {
"description": "The status of this system. Systems must be in UP status to be used.",
"enum": [
"UP",
"DOWN",
"UNKNOWN"
],
"type": "string"
},
"type": {
"description": "The type of this system.",
"enum": [
"EXECUTION",
"STORAGE"
],
"type": "string"
}
},
"required": [],
"title": "AgavePy SystemSummary schema",
"type": "object"
}
delete: Delete a system.¶
agavepy.systems.delete(systemId)
Parameters:¶
- systemId: The unique id of the system (string)
Response:¶
- String
get: Find information about an individual system.¶
agavepy.systems.get(systemId)
Parameters:¶
- systemId: The unique id of the system (string)
Response:¶
- A single System object
System schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/System.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"default": {
"description": "Is the system the default for the authenticated user?",
"type": "boolean"
},
"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"
},
"lastModified": {
"description": "The date this system was last modified in ISO 8601 format.",
"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"
},
"public": {
"description": "Is the system publicly available?",
"type": "boolean"
},
"queues": {
"description": "The execution paradigm used to run jobs on this system.",
"type": "array"
},
"revision": {
"description": "The number of times this app has been updated.",
"type": "int"
},
"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"
},
"uuid": {
"description": "The uuid of this system.",
"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": [],
"title": "AgavePy System schema",
"type": "object"
}
manage: Perform a management action on the system.¶
agavepy.systems.manage(body, systemId)
Parameters:¶
- systemId: The unique id of the system (string)
- body: The description of the system to update. (JSON, SystemOperationRequest)
SystemOperationRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/SystemOperationRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"description": "Action to perform on the system.",
"enum": [
"ENABLE",
"DISABLE",
"PUBLISH",
"UNPUBLISH",
"SETDEFAULT",
"UNSETDEFAULT",
"SETGLOBALDEFAULT",
"UNSETGLOBALDEFAULT",
"CLONE"
],
"type": "string"
},
"id": {
"description": "The new system id of the cloned system",
"type": "string"
}
},
"required": [
"action"
],
"title": "AgavePy SystemOperationRequest schema",
"type": "object"
}
Response:¶
- String
update: Find information about an individual system.¶
agavepy.systems.update(body, systemId)
Parameters:¶
- systemId: The unique id of the system (string)
- body: The description of the system to 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",
"scheduler",
"name",
"queues",
"storage",
"executionType",
"login",
"type"
],
"title": "AgavePy SystemRequest schema",
"type": "object"
}
Response:¶
- A single System object
System schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/System.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"default": {
"description": "Is the system the default for the authenticated user?",
"type": "boolean"
},
"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"
},
"lastModified": {
"description": "The date this system was last modified in ISO 8601 format.",
"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"
},
"public": {
"description": "Is the system publicly available?",
"type": "boolean"
},
"queues": {
"description": "The execution paradigm used to run jobs on this system.",
"type": "array"
},
"revision": {
"description": "The number of times this app has been updated.",
"type": "int"
},
"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"
},
"uuid": {
"description": "The uuid of this system.",
"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": [],
"title": "AgavePy System schema",
"type": "object"
}
deleteRoles: Deletes all roles on a system.¶
agavepy.systems.deleteRoles(systemId)
Parameters:¶
- systemId: The id of the system. (string)
Response:¶
- String
listRoles: Get a list of all users and their roles on this system.¶
agavepy.systems.listRoles(systemId, limit=250, offset=0)
Parameters:¶
- systemId: The id of the system. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of SystemRole objects
SystemRole schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/SystemRole.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"role": {
"description": "The role granted this user.",
"enum": [
"USER",
"PUBLISHER",
"ADMIN",
"OWNER"
],
"type": "string"
},
"username": {
"description": "The username of the api user granted this role.",
"type": "string"
}
},
"required": [],
"title": "AgavePy SystemRole schema",
"type": "object"
}
updateRole: Add or update a user’s role on a system.¶
agavepy.systems.updateRole(body, systemId)
Parameters:¶
- systemId: The id of the system. (string)
- body: The role to update. (JSON, SystemRole)
SystemRole schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/SystemRole.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"role": {
"description": "The role granted this user.",
"enum": [
"USER",
"PUBLISHER",
"ADMIN",
"OWNER"
],
"type": "string"
},
"username": {
"description": "The username of the api user granted this role.",
"type": "string"
}
},
"required": [],
"title": "AgavePy SystemRole schema",
"type": "object"
}
Response:¶
- String
deleteRoleForUser: Deletes all roles on a system.¶
agavepy.systems.deleteRoleForUser(systemId, username)
Parameters:¶
- 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.¶
agavepy.systems.getRoleForUser(systemId, username, limit=250, offset=0)
Parameters:¶
- systemId: The id of the system. (string)
- username: The username of the user about whose role you are inquiring. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single SystemRole object
SystemRole schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/SystemRole.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"role": {
"description": "The role granted this user.",
"enum": [
"USER",
"PUBLISHER",
"ADMIN",
"OWNER"
],
"type": "string"
},
"username": {
"description": "The username of the api user granted this role.",
"type": "string"
}
},
"required": [],
"title": "AgavePy SystemRole schema",
"type": "object"
}
updateRoleForUser: Add or update a user’s role on a system.¶
agavepy.systems.updateRoleForUser(body, systemId, username)
Parameters:¶
- systemId: The id of the system. (string)
- username: The username of the api user associated with the role (string)
- body: The role to update. (JSON, SystemRole)
SystemRole schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/SystemRole.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"role": {
"description": "The role granted this user.",
"enum": [
"USER",
"PUBLISHER",
"ADMIN",
"OWNER"
],
"type": "string"
},
"username": {
"description": "The username of the api user granted this role.",
"type": "string"
}
},
"required": [],
"title": "AgavePy SystemRole schema",
"type": "object"
}
Response:¶
- String
deleteCredentials: Deletes all credentials registered to a system.¶
agavepy.systems.deleteCredentials(systemId)
Parameters:¶
- systemId: The id of the system. (string)
Response:¶
- String
listCredentials: Get a list of all internal users and their credentials on this system.¶
agavepy.systems.listCredentials(systemId, limit=250, offset=0)
Parameters:¶
- systemId: The id of the system. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single StoredCredential object
StoredCredential schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/StoredCredential.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"credential": {
"description": "The credential used to authenticate to the remote system. Depending on the authentication protocol of the remote system, this could be an OAuth Token, X.509 certificate, Kerberose token, or an private key..",
"type": "string"
},
"default": {
"description": "Is this the default credential for this internal user of this type on this system?",
"type": "boolean"
},
"expirationDate": {
"description": "The date the credential expires in ISO 8601 format.",
"type": "string"
},
"internalUsername": {
"description": "The username of the internal user associated with this credential.",
"type": "string"
},
"parentType": {
"description": "The system type this credential is associated with.",
"enum": [
"STORAGE",
"EXECUTION"
],
"type": "string"
},
"password": {
"description": "The password on the remote system used to authenticate.",
"type": "string"
},
"privateKey": {
"description": "The public ssh key used to authenticate to the remote system..",
"type": "string"
},
"publicKey": {
"description": "The public ssh key used to authenticate to the remote system.",
"type": "string"
},
"server": {
"description": "The server from which a credential may be obtained.",
"type": "UserCredentialServer"
},
"type": {
"description": "The authentication type.",
"enum": [
"LOCAL",
"PAM",
"PASSWORD",
"SSHKEYS",
"TOKEN",
"X509"
],
"type": "string"
},
"username": {
"description": "The local username on the remote system used to authenticate.",
"type": "string"
},
"valid": {
"description": "Is the credential still valid or has it expired?.",
"type": "boolean"
}
},
"required": [
"username",
"type"
],
"title": "AgavePy StoredCredential schema",
"type": "object"
}
updateCredentials: Add or update a user’s credential on a system. This applies both to data and, if applicable, login credenitals.¶
agavepy.systems.updateCredentials(body, systemId)
Parameters:¶
- systemId: The id of the system. (string)
- body: The description of the internal user credential to add or update. (JSON, UserCredential)
UserCredential schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/UserCredential.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"credential": {
"description": "The credential used to authenticate to the remote system. Depending on the authentication protocol of the remote system, this could be an OAuth Token, X.509 certificate, Kerberose token, or an private key..",
"type": "string"
},
"internalUsername": {
"description": "The username of the internal user associated with this credential.",
"type": "string"
},
"password": {
"description": "The password on the remote system used to authenticate.",
"type": "string"
},
"privateKey": {
"description": "The public ssh key used to authenticate to the remote system..",
"type": "string"
},
"publicKey": {
"description": "The public ssh key used to authenticate to the remote system.",
"type": "string"
},
"server": {
"description": "The server from which a credential may be obtained.",
"type": "UserCredentialServer"
},
"type": {
"description": "The authentication type.",
"enum": [
"LOCAL",
"PAM",
"PASSWORD",
"SSHKEYS",
"TOKEN",
"X509"
],
"type": "string"
},
"username": {
"description": "The local username on the remote system used to authenticate.",
"type": "string"
}
},
"required": [
"type"
],
"title": "AgavePy UserCredential schema",
"type": "object"
}
Response:¶
- String
deleteCredentialsForInternalUser: Deletes all credentials registered to a system.¶
agavepy.systems.deleteCredentialsForInternalUser(internalUsername, systemId)
Parameters:¶
- systemId: The id of the system. (string)
- internalUsername: The username of a internal user on this system. (string)
Response:¶
- String
listCredentialsForInternalUser: Get a list of all internal users and their credentials on this system.¶
agavepy.systems.listCredentialsForInternalUser(internalUsername, systemId, limit=250, offset=0)
Parameters:¶
- systemId: The id of the system. (string)
- internalUsername: The username of a internal user on this system. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single StoredCredential object
StoredCredential schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/StoredCredential.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"credential": {
"description": "The credential used to authenticate to the remote system. Depending on the authentication protocol of the remote system, this could be an OAuth Token, X.509 certificate, Kerberose token, or an private key..",
"type": "string"
},
"default": {
"description": "Is this the default credential for this internal user of this type on this system?",
"type": "boolean"
},
"expirationDate": {
"description": "The date the credential expires in ISO 8601 format.",
"type": "string"
},
"internalUsername": {
"description": "The username of the internal user associated with this credential.",
"type": "string"
},
"parentType": {
"description": "The system type this credential is associated with.",
"enum": [
"STORAGE",
"EXECUTION"
],
"type": "string"
},
"password": {
"description": "The password on the remote system used to authenticate.",
"type": "string"
},
"privateKey": {
"description": "The public ssh key used to authenticate to the remote system..",
"type": "string"
},
"publicKey": {
"description": "The public ssh key used to authenticate to the remote system.",
"type": "string"
},
"server": {
"description": "The server from which a credential may be obtained.",
"type": "UserCredentialServer"
},
"type": {
"description": "The authentication type.",
"enum": [
"LOCAL",
"PAM",
"PASSWORD",
"SSHKEYS",
"TOKEN",
"X509"
],
"type": "string"
},
"username": {
"description": "The local username on the remote system used to authenticate.",
"type": "string"
},
"valid": {
"description": "Is the credential still valid or has it expired?.",
"type": "boolean"
}
},
"required": [
"username",
"type"
],
"title": "AgavePy StoredCredential schema",
"type": "object"
}
updateCredentialsForInternalUser: Add or update a user’s credentials on a system.¶
agavepy.systems.updateCredentialsForInternalUser(body, internalUsername, systemId)
Parameters:¶
- systemId: The id of the system. (string)
- internalUsername: The username of a internal user on this system. (string)
- body: The description of the internal user credential to add or update. (JSON, UserCredential)
UserCredential schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/UserCredential.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"credential": {
"description": "The credential used to authenticate to the remote system. Depending on the authentication protocol of the remote system, this could be an OAuth Token, X.509 certificate, Kerberose token, or an private key..",
"type": "string"
},
"internalUsername": {
"description": "The username of the internal user associated with this credential.",
"type": "string"
},
"password": {
"description": "The password on the remote system used to authenticate.",
"type": "string"
},
"privateKey": {
"description": "The public ssh key used to authenticate to the remote system..",
"type": "string"
},
"publicKey": {
"description": "The public ssh key used to authenticate to the remote system.",
"type": "string"
},
"server": {
"description": "The server from which a credential may be obtained.",
"type": "UserCredentialServer"
},
"type": {
"description": "The authentication type.",
"enum": [
"LOCAL",
"PAM",
"PASSWORD",
"SSHKEYS",
"TOKEN",
"X509"
],
"type": "string"
},
"username": {
"description": "The local username on the remote system used to authenticate.",
"type": "string"
}
},
"required": [
"type"
],
"title": "AgavePy UserCredential schema",
"type": "object"
}
Response:¶
- String
deleteCredentialsForInternalUserByType: Deletes the internal user credentials for the given credential type on a system.¶
agavepy.systems.deleteCredentialsForInternalUserByType(credentialType, internalUsername, systemId)
Parameters:¶
- systemId: The id of the system. (string)
- internalUsername: The username of a internal user on this system. (string)
- credentialType: The configuration type to which to apply this credential. (string)
Response:¶
- String
listCredentialsForInternalUserByType: Get the internal user credential of the given type on the system.¶
agavepy.systems.listCredentialsForInternalUserByType(credentialType, internalUsername, systemId, limit=250, offset=0)
Parameters:¶
- systemId: The id of the system. (string)
- internalUsername: The username of a internal user on this system. (string)
- credentialType: The configuration type to which to apply this credential. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single StoredCredential object
StoredCredential schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/StoredCredential.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"credential": {
"description": "The credential used to authenticate to the remote system. Depending on the authentication protocol of the remote system, this could be an OAuth Token, X.509 certificate, Kerberose token, or an private key..",
"type": "string"
},
"default": {
"description": "Is this the default credential for this internal user of this type on this system?",
"type": "boolean"
},
"expirationDate": {
"description": "The date the credential expires in ISO 8601 format.",
"type": "string"
},
"internalUsername": {
"description": "The username of the internal user associated with this credential.",
"type": "string"
},
"parentType": {
"description": "The system type this credential is associated with.",
"enum": [
"STORAGE",
"EXECUTION"
],
"type": "string"
},
"password": {
"description": "The password on the remote system used to authenticate.",
"type": "string"
},
"privateKey": {
"description": "The public ssh key used to authenticate to the remote system..",
"type": "string"
},
"publicKey": {
"description": "The public ssh key used to authenticate to the remote system.",
"type": "string"
},
"server": {
"description": "The server from which a credential may be obtained.",
"type": "UserCredentialServer"
},
"type": {
"description": "The authentication type.",
"enum": [
"LOCAL",
"PAM",
"PASSWORD",
"SSHKEYS",
"TOKEN",
"X509"
],
"type": "string"
},
"username": {
"description": "The local username on the remote system used to authenticate.",
"type": "string"
},
"valid": {
"description": "Is the credential still valid or has it expired?.",
"type": "boolean"
}
},
"required": [
"username",
"type"
],
"title": "AgavePy StoredCredential schema",
"type": "object"
}
updateCredentialsForInternalUserByType: Add or update a credential of the given type on a system.¶
agavepy.systems.updateCredentialsForInternalUserByType(body, credentialType, internalUsername, systemId)
Parameters:¶
- systemId: The id of the system. (string)
- internalUsername: The username of a internal user on this system. (string)
- credentialType: The configuration type to which to apply this credential. (string)
- body: The description of the internal user credential to add or update. (JSON, UserCredential)
UserCredential schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/UserCredential.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"credential": {
"description": "The credential used to authenticate to the remote system. Depending on the authentication protocol of the remote system, this could be an OAuth Token, X.509 certificate, Kerberose token, or an private key..",
"type": "string"
},
"internalUsername": {
"description": "The username of the internal user associated with this credential.",
"type": "string"
},
"password": {
"description": "The password on the remote system used to authenticate.",
"type": "string"
},
"privateKey": {
"description": "The public ssh key used to authenticate to the remote system..",
"type": "string"
},
"publicKey": {
"description": "The public ssh key used to authenticate to the remote system.",
"type": "string"
},
"server": {
"description": "The server from which a credential may be obtained.",
"type": "UserCredentialServer"
},
"type": {
"description": "The authentication type.",
"enum": [
"LOCAL",
"PAM",
"PASSWORD",
"SSHKEYS",
"TOKEN",
"X509"
],
"type": "string"
},
"username": {
"description": "The local username on the remote system used to authenticate.",
"type": "string"
}
},
"required": [
"type"
],
"title": "AgavePy UserCredential schema",
"type": "object"
}
Response:¶
- String
Files¶
Here we will describe how AgavePy allows us to interact with the API to store and manage data. The methods provided by AgavePy will allow us to setup the data for Agave apps to use, to share with collaborators, or to setup for long term storage.
Working with files¶
If you have already initiated a session, authentication, and have a storage system setup then you start working with files.
Listing files and directories¶
Before we even get started, we should know what it is we are going to be
working with.
To see any files or directories in your remote storage system, let’s say this
is called data-tacc-user.
>>> agave.files_list("/data-tacc-user")
./ .slurm/ apps/ benchmarks/
bigfile cptests/ users/ myotherfile
old-sd2e-apps/ rpmbuild/ sd2e-apps/ sd2e-data/
singularity-test/ somefile SP1-copy.fq SP1.fq
tests/
For more details, such as permissions and size:
>>> agave.files_list("data-tacc-user/", long_format=True)
drwx 4096 Oct 25 14:47 ./
drwx 4096 May 25 16:13 .slurm/
drwx 4096 Jun 5 10:14 apps/
drwx 4096 Jun 9 18:39 benchmarks/
-rw- 1073741824 Oct 25 14:48 bigfile
drwx 4096 Jul 13 09:17 cptests/
drwx 4096 Aug 1 14:26 users/
-rw- 24 Oct 25 14:42 myotherfile
drwx 4096 Jul 10 11:27 old-sd2e-apps/
drwx 4096 Jun 29 10:40 rpmbuild/
drwx 4096 Jul 13 15:41 sd2e-apps/
drwx 4096 Jul 7 20:43 sd2e-data/
drwx 4096 Jul 9 16:50 singularity-test/
-rw- 24 Oct 25 14:20 somefile
-rw- 22471 Aug 22 14:40 SP1-copy.fq
-rw- 22471 Jul 7 20:42 SP1.fq
drwx 4096 Aug 24 13:44 tests/
Download a file¶
Let’s say you have a file named SP1.fq on your remote storage system,
data-tacc-user.
You can download the file, SP1.fq, to your host and specify the location of
where you want to store the file (i.e., /opt/data/SP1.fq) as such:
>>> agave.files_download("data-tacc-user/SP1.fq", "/opt/data/SP1.fq")
Upload a file¶
Similarly, if you want to upload a file, data.ext, and you
want to save it on your stoorage system named, data-tacc-user under
the name cool_data.bin.
>>> agave.files_upload("./data.ext", "data-tacc-user/cool.ext")
Make a copy of a file on a remote system¶
So now, you have a cool.ext file on your remote storage
system, data-tacc-user. Let’s make a copy of it!
>>> agave.files_copy("data-tacc-user/cool.ext", "data-tacc-user/copy.ext")
Move files¶
To move files around on a remote storage system, you can do so as follows:
>>> agave.files_move("data-tacc-user/file.ext", "data-tacc-user/dir/file.ext")
Delete a file¶
On the other hand, if there is a file or directory that you want to get rid off:
>>> agave.files_delete("data-tacc-user/somefile-or-directory")
Import files from ther systems¶
It may be useful to import data from other storage systems, e.g. from the
community data space to your private data space.
The files_import method can be used for that purpose.
agave.files_import("agave://data-community/test.txt", "system-id/")
Please also note that even though you are able to import files from other Agave
storage systems, you may not always need to import those files.
Also, note that the source, the first argument, must be an agave compliant uri
by prefixing the system if and path convination with the string agave://.
Making a directory¶
AgavePy also provides mkdir-like functionality.
To create a directory on a remote storage system:
>>> agave.files_mkdir("data-tacc-user/new_dir")
Managing Files¶
Managing permissions¶
Use files-pems-list to list the user permissions associated with a file or
folder. These permissions are set at the API level and do not reflect unix-like
or other file system ACL.
>>> ag.files_pems_list("system-id/some-dir")
USER READ WRITE EXEC
username yes yes yes
To remove all the permissions on a file, except those of the owner:
agave.files_pems_delete("system-id/some-dir")
To edit permissions for another user, let’s say her username is “collab,” to view a file:
ag.files_pems_update("system-id/path", "collab", "ALL", recursive=True)
Now, a user with username “collab” has permissions to access the all contents
of the specified directory (hence the recursive=True option).
Valid values for setting permission are READ, WRITE, EXECUTE,
READ_WRITE, READ_EXECUTE, WRITE_EXECUTE, ALL, and NONE.
This same action can be performed recursively on directories using recursive=True.
File or Directory History¶
You can list the history of events for a specific file or folder. This will give more descriptive information (when applicable) related to number of retries, permission grants and revocations, reasons for failure, and hiccups that may have occurred in a recent process.
>>> ag.files_history("system-id/path/to/dir")
USER EVENT DATE DESCRIPTION
username CREATED 2018-11-02T10:08:54.000-05:00 New directory created at https://api.sd2e.org/files/v2/media/system/system-id//path/to/dir
username PERMISSION_REVOKE 2018-11-30T11:22:01.000-06:00 All permissions revoked
username PERMISSION_GRANT 2018-12-03T10:11:07.000-06:00 OWNER permission granted to collaborator
Other methods available¶
Summary: Move and manage data
deleteFromDefaultSystem: Deletes a file or folder.¶
agavepy.files.deleteFromDefaultSystem(sourcefilePath)
Parameters:¶
- 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.¶
agavepy.files.downloadFromDefaultSystem(sourcefilePath)
Parameters:¶
- 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.¶
agavepy.files.importToDefaultSystem(sourcefilePath, callbackURL=None, fileName=None, fileToUpload=None, fileType=None, urlToIngest=None)
Parameters:¶
- sourcefilePath: The path of the file relative to the user’s default storage location. (string)
- fileType: The file format this file is in. Defaults to raw. This will be used in file transform operations. (string)
- 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)
- fileName: The name of the file after importing. If not specified, the uploaded file name will be used. (string)
- urlToIngest: The URL to import the file from. This parameter is used if not file is uploaded with this post. (string)
- fileToUpload: The file object to import. (void)
Response:¶
- A single RemoteFile object
RemoteFile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/RemoteFile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"format": {
"description": "The file type of the file.",
"type": "string"
},
"lastModified": {
"description": "The date this file was last modified in ISO 8601 format.",
"type": "string"
},
"length": {
"description": "The length of the file/folder.",
"type": "integer"
},
"mimeType": {
"description": "The mime type of the file/folder. If unknown, it defaults to application/binary.",
"type": "string"
},
"name": {
"description": "The name of the file/folder.",
"type": "string"
},
"path": {
"description": "The absolute path to the file/folder.",
"type": "string"
},
"permissions": {
"description": "The system permission of the invoking user on the file/folder.",
"type": "string"
},
"system": {
"description": "The systemId of the system where this file lives.",
"type": "string"
},
"type": {
"description": "Whether it is a file or folder.",
"type": "string"
}
},
"required": [],
"title": "AgavePy RemoteFile schema",
"type": "object"
}
manageOnDefaultSystem: Perform an action on a file or folder.¶
agavepy.files.manageOnDefaultSystem(body, sourcefilePath)
Parameters:¶
- sourcefilePath: The path of the file relative to the user’s default storage location. (string)
- body: The operation to perform. (JSON, FileOperationRequest)
FileOperationRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FileOperationRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"description": "Action to perform on the file or folder.",
"enum": [
"mkdir",
"rename",
"copy",
"move"
],
"type": "string"
},
"path": {
"description": "Destination file or folder.",
"type": "string"
}
},
"required": [
"action"
],
"title": "AgavePy FileOperationRequest schema",
"type": "object"
}
Response:¶
- String
delete: Deletes a file or folder.¶
agavepy.files.delete(filePath, systemId)
Parameters:¶
- systemId: The unique id of the system on which the data resides. (string)
- filePath: The path of the file relative to the user’s default storage location. (string)
Response:¶
- String
download: Download a file from the user’s default storage location.¶
agavepy.files.download(filePath, systemId)
Parameters:¶
- systemId: The unique id of the system on which the data resides. (string)
- filePath: The path of the file relative to the user’s default storage location. (string)
Response:¶
- None
importData: Import a file via direct upload or importing from a url to the user’s default storage location.¶
agavepy.files.importData(filePath, systemId, callbackURL=None, fileName=None, fileToUpload=None, fileType=None, notifications=[], urlToIngest=None)
Parameters:¶
- systemId: The unique id of the system on which the data resides. (string)
- filePath: The path of the file relative to the user’s default storage location. (string)
- fileType: The file format this file is in. Defaults to raw. This will be used in file transform operations. (string)
- 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)
- fileName: The name of the file after importing. If not specified, the uploaded file name will be used. (string)
- urlToIngest: The URL to import the file from. This parameter is used if not file is uploaded with this post. (string)
- fileToUpload: The file object to import. (void)
- notifications: A list of notification objects to apply to the transfer. (FileNotificationRequest)
Response:¶
- A single RemoteFile object
RemoteFile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/RemoteFile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"format": {
"description": "The file type of the file.",
"type": "string"
},
"lastModified": {
"description": "The date this file was last modified in ISO 8601 format.",
"type": "string"
},
"length": {
"description": "The length of the file/folder.",
"type": "integer"
},
"mimeType": {
"description": "The mime type of the file/folder. If unknown, it defaults to application/binary.",
"type": "string"
},
"name": {
"description": "The name of the file/folder.",
"type": "string"
},
"path": {
"description": "The absolute path to the file/folder.",
"type": "string"
},
"permissions": {
"description": "The system permission of the invoking user on the file/folder.",
"type": "string"
},
"system": {
"description": "The systemId of the system where this file lives.",
"type": "string"
},
"type": {
"description": "Whether it is a file or folder.",
"type": "string"
}
},
"required": [],
"title": "AgavePy RemoteFile schema",
"type": "object"
}
manage: Perform an action on a file or folder.¶
agavepy.files.manage(body, filePath, systemId)
Parameters:¶
- systemId: The unique id of the system on which the data resides. (string)
- filePath: The path of the file relative to the user’s default storage location. (string)
- body: The operation to perform. (JSON, FileOperationRequest)
FileOperationRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FileOperationRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"description": "Action to perform on the file or folder.",
"enum": [
"mkdir",
"rename",
"copy",
"move"
],
"type": "string"
},
"path": {
"description": "Destination file or folder.",
"type": "string"
}
},
"required": [
"action"
],
"title": "AgavePy FileOperationRequest schema",
"type": "object"
}
Response:¶
- String
listOnDefaultSystem: Get a remote directory listing.¶
agavepy.files.listOnDefaultSystem(filePath, limit=250, offset=0)
Parameters:¶
- filePath: The path of the file relative to the user’s default storage location. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of RemoteFile objects
RemoteFile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/RemoteFile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"format": {
"description": "The file type of the file.",
"type": "string"
},
"lastModified": {
"description": "The date this file was last modified in ISO 8601 format.",
"type": "string"
},
"length": {
"description": "The length of the file/folder.",
"type": "integer"
},
"mimeType": {
"description": "The mime type of the file/folder. If unknown, it defaults to application/binary.",
"type": "string"
},
"name": {
"description": "The name of the file/folder.",
"type": "string"
},
"path": {
"description": "The absolute path to the file/folder.",
"type": "string"
},
"permissions": {
"description": "The system permission of the invoking user on the file/folder.",
"type": "string"
},
"system": {
"description": "The systemId of the system where this file lives.",
"type": "string"
},
"type": {
"description": "Whether it is a file or folder.",
"type": "string"
}
},
"required": [],
"title": "AgavePy RemoteFile schema",
"type": "object"
}
list: Get a remote directory listing on a specific system.¶
agavepy.files.list(filePath, systemId, limit=250, offset=0)
Parameters:¶
- systemId: The unique id of the system on which the data resides. (string)
- filePath: The path of the file relative to the user’s default storage location. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of RemoteFile objects
RemoteFile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/RemoteFile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"format": {
"description": "The file type of the file.",
"type": "string"
},
"lastModified": {
"description": "The date this file was last modified in ISO 8601 format.",
"type": "string"
},
"length": {
"description": "The length of the file/folder.",
"type": "integer"
},
"mimeType": {
"description": "The mime type of the file/folder. If unknown, it defaults to application/binary.",
"type": "string"
},
"name": {
"description": "The name of the file/folder.",
"type": "string"
},
"path": {
"description": "The absolute path to the file/folder.",
"type": "string"
},
"permissions": {
"description": "The system permission of the invoking user on the file/folder.",
"type": "string"
},
"system": {
"description": "The systemId of the system where this file lives.",
"type": "string"
},
"type": {
"description": "Whether it is a file or folder.",
"type": "string"
}
},
"required": [],
"title": "AgavePy RemoteFile schema",
"type": "object"
}
getHistoryOnDefaultSystem: Download a file from the user’s default storage location.¶
agavepy.files.getHistoryOnDefaultSystem(filePath, limit=250, offset=0)
Parameters:¶
- filePath: The path of the file relative to the user’s default storage location. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of FileHistory objects
FileHistory schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FileHistory.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "The date of the event.",
"type": "string"
},
"description": {
"description": "A brief description of the event details.",
"type": "String"
},
"status": {
"description": "The status of the file/folder after this event.",
"type": "String"
}
},
"required": [],
"title": "AgavePy FileHistory schema",
"type": "object"
}
getHistory: Return history of api actions.¶
agavepy.files.getHistory(filePath, systemId, limit=250, offset=0)
Parameters:¶
- systemId: The unique id of the system on which the data resides. (string)
- filePath: The path of the file relative to the given system root location. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of FileHistory objects
FileHistory schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FileHistory.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "The date of the event.",
"type": "string"
},
"description": {
"description": "A brief description of the event details.",
"type": "String"
},
"status": {
"description": "The status of the file/folder after this event.",
"type": "String"
}
},
"required": [],
"title": "AgavePy FileHistory schema",
"type": "object"
}
updatePermissionsOnDefaultSystem: Update permissions for a single user.¶
agavepy.files.updatePermissionsOnDefaultSystem(body, filePath)
Parameters:¶
- filePath: The path of the file relative to the user’s default storage location. (string)
- body: The permission add or update. (JSON, FilePermissionRequest)
FilePermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FilePermissionRequest.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"
},
"recursive": {
"description": "Should updated permissions be applied recursively. Defaults to false.",
"type": "boolean"
},
"username": {
"description": "The username of the api user whose permission is to be set.",
"type": "string"
}
},
"required": [
"username",
"permission"
],
"title": "AgavePy FilePermissionRequest schema",
"type": "object"
}
Response:¶
- String
deletePermissions: Deletes all permissions on a file except those of the owner.¶
agavepy.files.deletePermissions(filePath, systemId)
Parameters:¶
- 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.¶
agavepy.files.updatePermissions(body, filePath, systemId)
Parameters:¶
- 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)
- body: The permission add or update. (JSON, FilePermissionRequest)
FilePermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FilePermissionRequest.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"
},
"recursive": {
"description": "Should updated permissions be applied recursively. Defaults to false.",
"type": "boolean"
},
"username": {
"description": "The username of the api user whose permission is to be set.",
"type": "string"
}
},
"required": [
"username",
"permission"
],
"title": "AgavePy FilePermissionRequest schema",
"type": "object"
}
Response:¶
- Array of FilePermission objects
FilePermission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/FilePermission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"description": "The name of the file/folder.",
"type": "string"
},
"owner": {
"description": "Local username of the owner.",
"type": "string"
},
"permissions": {
"description": "One or more permission objects",
"type": "array"
}
},
"required": [],
"title": "AgavePy FilePermission schema",
"type": "object"
}
Apps¶
Agave allows users to build and run applications through its API. Here we will walk through the methods available to interact use apps using AgavePy.
Apps¶
Summary: Register and manage apps
add: Register and update new applications.¶
agavepy.apps.add(body)
Parameters:¶
- 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": [
"available",
"inputs",
"executionSystem",
"testPath",
"deploymentPath",
"templatePath",
"deploymentSystem",
"name",
"parameters",
"executionType",
"version"
],
"title": "AgavePy ApplicationRequest schema",
"type": "object"
}
Response:¶
- A single Application object
Application schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Application.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": "string"
},
"defaultMemoryPerNode": {
"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"
},
"defaultProcessorsPerNode": {
"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": "string"
},
"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"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"inputs": {
"description": "The inputs files for this application. ",
"type": "array"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"label": {
"description": "The label to use when generating forms.",
"type": "string"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"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"
},
"uuid": {
"description": "The UUID of this application. UUID are 36 alphanumeric string.",
"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": [],
"title": "AgavePy Application schema",
"type": "object"
}
list: Get a list of available applications.¶
agavepy.apps.list(limit=250, offset=0, privateOnly=None, publicOnly=None)
Parameters:¶
- publicOnly: Whether to return only public apps. (boolean)
- privateOnly: Whether to return only private apps. (boolean)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of ApplicationSummary objects
ApplicationSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ApplicationSummary.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"executionSystem": {
"description": "The system id of the execution system where this app should run.",
"type": "string"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"type": "string"
},
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"shortDescription": {
"description": "The short description of this application.",
"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": [],
"title": "AgavePy ApplicationSummary schema",
"type": "object"
}
delete: Deletes an application.¶
agavepy.apps.delete(appId)
Parameters:¶
- 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.¶
agavepy.apps.get(appId)
Parameters:¶
- 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
Application schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Application.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": "string"
},
"defaultMemoryPerNode": {
"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"
},
"defaultProcessorsPerNode": {
"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": "string"
},
"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"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"inputs": {
"description": "The inputs files for this application. ",
"type": "array"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"label": {
"description": "The label to use when generating forms.",
"type": "string"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"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"
},
"uuid": {
"description": "The UUID of this application. UUID are 36 alphanumeric string.",
"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": [],
"title": "AgavePy Application schema",
"type": "object"
}
manage: Edit an application.¶
agavepy.apps.manage(appId, body)
Parameters:¶
- 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
Application schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Application.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": "string"
},
"defaultMemoryPerNode": {
"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"
},
"defaultProcessorsPerNode": {
"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": "string"
},
"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"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"inputs": {
"description": "The inputs files for this application. ",
"type": "array"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"label": {
"description": "The label to use when generating forms.",
"type": "string"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"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"
},
"uuid": {
"description": "The UUID of this application. UUID are 36 alphanumeric string.",
"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": [],
"title": "AgavePy Application schema",
"type": "object"
}
update: Update an application.¶
agavepy.apps.update(appId, body)
Parameters:¶
- 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": [
"available",
"inputs",
"executionSystem",
"testPath",
"deploymentPath",
"templatePath",
"deploymentSystem",
"name",
"parameters",
"executionType",
"version"
],
"title": "AgavePy ApplicationRequest schema",
"type": "object"
}
Response:¶
- A single Application object
Application schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Application.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": "string"
},
"defaultMemoryPerNode": {
"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"
},
"defaultProcessorsPerNode": {
"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": "string"
},
"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"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"inputs": {
"description": "The inputs files for this application. ",
"type": "array"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"label": {
"description": "The label to use when generating forms.",
"type": "string"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"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"
},
"uuid": {
"description": "The UUID of this application. UUID are 36 alphanumeric string.",
"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": [],
"title": "AgavePy Application schema",
"type": "object"
}
deletePermissions: Deletes all permissions on an application.¶
agavepy.apps.deletePermissions(appId)
Parameters:¶
- 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.¶
agavepy.apps.listPermissions(appId, limit=250, offset=0)
Parameters:¶
- 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)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of ApplicationPermission objects
ApplicationPermission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ApplicationPermission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy ApplicationPermission schema",
"type": "object"
}
updateApplicationPermissions: Add or update a user’s permission for an application.¶
agavepy.apps.updateApplicationPermissions(appId, body)
Parameters:¶
- 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.¶
agavepy.apps.deletePermissionsForUser(appId, username)
Parameters:¶
- 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.¶
agavepy.apps.listPermissionsForUser(appId, username, limit=250, offset=0)
Parameters:¶
- 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)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of ApplicationPermission objects
ApplicationPermission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ApplicationPermission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy ApplicationPermission schema",
"type": "object"
}
updatePermissionsForUser: Add or update a user’s permission for an application.¶
agavepy.apps.updatePermissionsForUser(appId, body, username)
Parameters:¶
- 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)
- 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
listByName: Get a list of applications with the given name.¶
agavepy.apps.listByName(name, limit=250, offset=0, privateOnly=None, publicOnly=None)
Parameters:¶
- name: The name of the application. This should not include the version number. (string)
- publicOnly: Whether to return only public apps. (boolean)
- privateOnly: Whether to return only private apps. (boolean)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of ApplicationSummary objects
ApplicationSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ApplicationSummary.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"executionSystem": {
"description": "The system id of the execution system where this app should run.",
"type": "string"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"type": "string"
},
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"shortDescription": {
"description": "The short description of this application.",
"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": [],
"title": "AgavePy ApplicationSummary schema",
"type": "object"
}
listBySystemId: Get a list of applications with the given systemId as their executionHost.¶
agavepy.apps.listBySystemId(systemId, limit=250, offset=0, privateOnly=None, publicOnly=None)
Parameters:¶
- systemId: The system in question (string)
- publicOnly: Whether to return only public apps. (boolean)
- privateOnly: Whether to return only private apps. (boolean)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of ApplicationSummary objects
ApplicationSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ApplicationSummary.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"executionSystem": {
"description": "The system id of the execution system where this app should run.",
"type": "string"
},
"id": {
"description": "Unique id of this app. Comprised of the app name-version.",
"type": "string"
},
"isPublic": {
"description": "Whether the application is public or private.",
"type": "boolean"
},
"lastModified": {
"description": "The date this application was last modified in ISO 8601 format.",
"type": "string"
},
"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"
},
"revision": {
"description": "The number of times this application has been revised.",
"type": "integer"
},
"shortDescription": {
"description": "The short description of this application.",
"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": [],
"title": "AgavePy ApplicationSummary schema",
"type": "object"
}
Jobs¶
Agave make job resources available to users so that these can be managed directly or through scripted applications.
Jobs¶
Summary: Run and manage jobs
list: Get a list of jobs the authenticated user had submitted.¶
agavepy.jobs.list(limit=250, offset=0)
Parameters:¶
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of JobSummary objects
JobSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobSummary.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"
},
"endTime": {
"description": "The date the job ended in ISO 8601 format.",
"type": "string"
},
"executionSystem": {
"description": "The system id of the execution system.",
"type": "string"
},
"id": {
"description": "The unique id of the job.",
"type": "string"
},
"name": {
"description": "The name of the job.",
"type": "string"
},
"owner": {
"description": "The job owner.",
"type": "string"
},
"startTime": {
"description": "The date the job started in ISO 8601 format.",
"type": "string"
},
"status": {
"description": "The status of the job. Possible values are: PENDING, STAGING_INPUTS, CLEANING_UP, ARCHIVING, STAGING_JOB, FINISHED, KILLED, FAILED, STOPPED, RUNNING, PAUSED, QUEUED, SUBMITTING, STAGED, PROCESSING_INPUTS, ARCHIVING_FINISHED, ARCHIVING_FAILED",
"type": "string"
}
},
"required": [],
"title": "AgavePy JobSummary schema",
"type": "object"
}
submit: Submit a new job request.¶
agavepy.jobs.submit(body)
Parameters:¶
- 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
Job schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Job.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"
},
"endTime": {
"description": "The date the job stopped running due to termination, completion, or error in ISO 8601 format.",
"type": "string"
},
"executionSystem": {
"description": "The system id of the execution system.",
"type": "string"
},
"id": {
"description": "The unique id of the job.",
"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"
},
"localId": {
"description": "The process or local job id of the job on the remote execution system.",
"type": "string"
},
"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"
},
"message": {
"description": "The error message incurred when the job failed.",
"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"
},
"outputPath": {
"description": "Relative path of the job's output data.",
"type": "String"
},
"owner": {
"description": "The job owner.",
"type": "string"
},
"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"
},
"retries": {
"description": "The number of retires it took to submit this job.",
"type": "integer"
},
"startTime": {
"description": "The date the job started in ISO 8601 format.",
"type": "string"
},
"status": {
"description": "The status of the job. Possible values are: PENDING, STAGING_INPUTS, CLEANING_UP, ARCHIVING, STAGING_JOB, FINISHED, KILLED, FAILED, STOPPED, RUNNING, PAUSED, QUEUED, SUBMITTING, STAGED, PROCESSING_INPUTS, ARCHIVING_FINISHED, ARCHIVING_FAILED",
"type": "string"
},
"submitTime": {
"description": "The date the job was submitted in ISO 8601 format.",
"type": "string"
},
"workPath": {
"description": "The directory on the remote execution system from which the job is running.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Job schema",
"type": "object"
}
delete: Deletes a job from the user’s history.¶
agavepy.jobs.delete(jobId)
Parameters:¶
- jobId: The id of the job. (string)
Response:¶
- String
get: Get details of the job with the specific job id.¶
agavepy.jobs.get(jobId)
Parameters:¶
- jobId: The id of the job. (string)
Response:¶
- A single Job object
Job schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Job.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"
},
"endTime": {
"description": "The date the job stopped running due to termination, completion, or error in ISO 8601 format.",
"type": "string"
},
"executionSystem": {
"description": "The system id of the execution system.",
"type": "string"
},
"id": {
"description": "The unique id of the job.",
"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"
},
"localId": {
"description": "The process or local job id of the job on the remote execution system.",
"type": "string"
},
"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"
},
"message": {
"description": "The error message incurred when the job failed.",
"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"
},
"outputPath": {
"description": "Relative path of the job's output data.",
"type": "String"
},
"owner": {
"description": "The job owner.",
"type": "string"
},
"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"
},
"retries": {
"description": "The number of retires it took to submit this job.",
"type": "integer"
},
"startTime": {
"description": "The date the job started in ISO 8601 format.",
"type": "string"
},
"status": {
"description": "The status of the job. Possible values are: PENDING, STAGING_INPUTS, CLEANING_UP, ARCHIVING, STAGING_JOB, FINISHED, KILLED, FAILED, STOPPED, RUNNING, PAUSED, QUEUED, SUBMITTING, STAGED, PROCESSING_INPUTS, ARCHIVING_FINISHED, ARCHIVING_FAILED",
"type": "string"
},
"submitTime": {
"description": "The date the job was submitted in ISO 8601 format.",
"type": "string"
},
"workPath": {
"description": "The directory on the remote execution system from which the job is running.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Job schema",
"type": "object"
}
manage: Perform an action on a job.¶
agavepy.jobs.manage(body, jobId)
Parameters:¶
- jobId: The id of the job. (string)
- body: The operation to perform. (JSON, JobOperationRequest)
JobOperationRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobOperationRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"action": {
"description": "Action to perform on the job.",
"enum": [
"resubmit",
"stop"
],
"type": "string"
}
},
"required": [
"action"
],
"title": "AgavePy JobOperationRequest schema",
"type": "object"
}
Response:¶
- A single Job object
Job schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Job.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"
},
"endTime": {
"description": "The date the job stopped running due to termination, completion, or error in ISO 8601 format.",
"type": "string"
},
"executionSystem": {
"description": "The system id of the execution system.",
"type": "string"
},
"id": {
"description": "The unique id of the job.",
"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"
},
"localId": {
"description": "The process or local job id of the job on the remote execution system.",
"type": "string"
},
"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"
},
"message": {
"description": "The error message incurred when the job failed.",
"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"
},
"outputPath": {
"description": "Relative path of the job's output data.",
"type": "String"
},
"owner": {
"description": "The job owner.",
"type": "string"
},
"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"
},
"retries": {
"description": "The number of retires it took to submit this job.",
"type": "integer"
},
"startTime": {
"description": "The date the job started in ISO 8601 format.",
"type": "string"
},
"status": {
"description": "The status of the job. Possible values are: PENDING, STAGING_INPUTS, CLEANING_UP, ARCHIVING, STAGING_JOB, FINISHED, KILLED, FAILED, STOPPED, RUNNING, PAUSED, QUEUED, SUBMITTING, STAGED, PROCESSING_INPUTS, ARCHIVING_FINISHED, ARCHIVING_FAILED",
"type": "string"
},
"submitTime": {
"description": "The date the job was submitted in ISO 8601 format.",
"type": "string"
},
"workPath": {
"description": "The directory on the remote execution system from which the job is running.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Job schema",
"type": "object"
}
getHistory: Get the history of this job.¶
agavepy.jobs.getHistory(jobId, limit=250, offset=0)
Parameters:¶
- jobId: The id of the job. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of JobHistory objects
JobHistory schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobHistory.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "The date of the event.",
"type": "string"
},
"description": {
"description": "A brief description of the event details.",
"type": "String"
},
"status": {
"description": "The status of the job after this event.",
"type": "String"
}
},
"required": [],
"title": "AgavePy JobHistory schema",
"type": "object"
}
deletePermissions: Deletes all permissions on an job.¶
agavepy.jobs.deletePermissions(jobId)
Parameters:¶
- jobId: The id of the job. (string)
Response:¶
- String
listPermissions: Get the permission ACL for this job.¶
agavepy.jobs.listPermissions(jobId, limit=250, offset=0)
Parameters:¶
- jobId: The id of the job. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of Permission objects
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
updatePermissions: Add or update a user’s permission for an application.¶
agavepy.jobs.updatePermissions(body, jobId)
Parameters:¶
- jobId: The id of the job. (string)
- body: The permission add or update. (JSON, JobPermissionRequest)
JobPermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobPermissionRequest.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 JobPermissionRequest schema",
"type": "object"
}
Response:¶
- String
deletePermissionsForUser: Deletes all permissions for the given user on an job.¶
agavepy.jobs.deletePermissionsForUser(uniqueName, username)
Parameters:¶
- 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.¶
agavepy.jobs.listPermissionsForUser(jobId, username, limit=250, offset=0)
Parameters:¶
- jobId: The id of the job. (string)
- username: The username of the api user associated with the permission. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of Permission objects
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
updatePermissionsForUser: Add or update a user’s permission for an job.¶
agavepy.jobs.updatePermissionsForUser(body, jobId, username)
Parameters:¶
- jobId: The id of the job. (string)
- username: The username of the api user associated with the permission (string)
- body: The permission to update. (JSON, JobPermissionRequest)
JobPermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobPermissionRequest.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 JobPermissionRequest schema",
"type": "object"
}
Response:¶
- String
getStatus: Get the status of the job.¶
agavepy.jobs.getStatus(jobId)
Parameters:¶
- jobId: The id of the job. (string)
Response:¶
- A single JobStatus object
JobStatus schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobStatus.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"description": "The unique id of the job.",
"type": "string"
},
"status": {
"description": "The status of the job. Possible values are: PENDING, STAGING_INPUTS, CLEANING_UP, ARCHIVING, STAGING_JOB, FINISHED, KILLED, FAILED, STOPPED, RUNNING, PAUSED, QUEUED, SUBMITTING, STAGED, PROCESSING_INPUTS, ARCHIVING_FINISHED, ARCHIVING_FAILED",
"type": "string"
}
},
"required": [],
"title": "AgavePy JobStatus schema",
"type": "object"
}
listOutputs: List contents of a job’s output directory.¶
agavepy.jobs.listOutputs(jobId, filePath=None, limit=250, offset=0)
Parameters:¶
- jobId: The id of the job. (string)
- 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)
- limit: max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of RemoteFile objects
RemoteFile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/RemoteFile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"format": {
"description": "The file type of the file.",
"type": "string"
},
"lastModified": {
"description": "The date this file was last modified in ISO 8601 format.",
"type": "string"
},
"length": {
"description": "The length of the file/folder.",
"type": "integer"
},
"mimeType": {
"description": "The mime type of the file/folder. If unknown, it defaults to application/binary.",
"type": "string"
},
"name": {
"description": "The name of the file/folder.",
"type": "string"
},
"path": {
"description": "The absolute path to the file/folder.",
"type": "string"
},
"permissions": {
"description": "The system permission of the invoking user on the file/folder.",
"type": "string"
},
"system": {
"description": "The systemId of the system where this file lives.",
"type": "string"
},
"type": {
"description": "Whether it is a file or folder.",
"type": "string"
}
},
"required": [],
"title": "AgavePy RemoteFile schema",
"type": "object"
}
downloadOutput: Download an output file from a specific job.¶
agavepy.jobs.downloadOutput(filePath, jobId)
Parameters:¶
- jobId: The id of the job. (string)
- filePath: Path to an output file relative to the job output directory. (string)
Response:¶
- None
search: Find jobs matching the given attribute/value combination(s).¶
agavepy.jobs.search(attribute, value, limit=250, offset=0)
Parameters:¶
- attribute: The attribute to query by. This can be any job field. (string)
- value: The value of the attribute to query for. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of JobSummary objects
JobSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/JobSummary.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"
},
"endTime": {
"description": "The date the job ended in ISO 8601 format.",
"type": "string"
},
"executionSystem": {
"description": "The system id of the execution system.",
"type": "string"
},
"id": {
"description": "The unique id of the job.",
"type": "string"
},
"name": {
"description": "The name of the job.",
"type": "string"
},
"owner": {
"description": "The job owner.",
"type": "string"
},
"startTime": {
"description": "The date the job started in ISO 8601 format.",
"type": "string"
},
"status": {
"description": "The status of the job. Possible values are: PENDING, STAGING_INPUTS, CLEANING_UP, ARCHIVING, STAGING_JOB, FINISHED, KILLED, FAILED, STOPPED, RUNNING, PAUSED, QUEUED, SUBMITTING, STAGED, PROCESSING_INPUTS, ARCHIVING_FINISHED, ARCHIVING_FAILED",
"type": "string"
}
},
"required": [],
"title": "AgavePy JobSummary schema",
"type": "object"
}
Metadata¶
Create and manage metadata using Agave.
Metadata¶
Summary: Create and manage metadata
addMetadata: Update or Add new Metadata.¶
agavepy.meta.addMetadata(body)
Parameters:¶
- 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
Metadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Metadata.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"
},
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this metadata.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata store.",
"type": "string"
},
"name": {
"description": "The name of this metadata",
"type": "string"
},
"owner": {
"description": "The API user who owns this Metadata.",
"type": "string"
},
"uuid": {
"description": "The UUID for this Metadata.",
"type": "string"
},
"value": {
"description": "A free text or JSON string containing the metadata stored for the given associationIds",
"type": "string"
}
},
"required": [],
"title": "AgavePy Metadata schema",
"type": "object"
}
listMetadata: List and/or search metadata.¶
agavepy.meta.listMetadata(limit=250, offset=0, privileged=True, q=None)
Parameters:¶
- q: The query to perform. Traditional MongoDB queries are supported (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
- privileged: If false, implicit permissions are ignored and only records to which the user has explicit permissions are returned (boolean)
Response:¶
- Array of MetadataResponse objects
deleteMetadata: Remove Metadata from the system.¶
agavepy.meta.deleteMetadata(uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
Response:¶
- A single EmptyMetadata object
EmptyMetadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyMetadata.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyMetadata schema",
"type": "object"
}
getMetadata: Retrieve Metadata.¶
agavepy.meta.getMetadata(uuid, limit=250, offset=0)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single Metadata object
Metadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Metadata.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"
},
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this metadata.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata store.",
"type": "string"
},
"name": {
"description": "The name of this metadata",
"type": "string"
},
"owner": {
"description": "The API user who owns this Metadata.",
"type": "string"
},
"uuid": {
"description": "The UUID for this Metadata.",
"type": "string"
},
"value": {
"description": "A free text or JSON string containing the metadata stored for the given associationIds",
"type": "string"
}
},
"required": [],
"title": "AgavePy Metadata schema",
"type": "object"
}
updateMetadata: Update or Add new Metadata.¶
agavepy.meta.updateMetadata(body, uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- body: The metadata to update. (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
Metadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Metadata.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"
},
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this metadata.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata store.",
"type": "string"
},
"name": {
"description": "The name of this metadata",
"type": "string"
},
"owner": {
"description": "The API user who owns this Metadata.",
"type": "string"
},
"uuid": {
"description": "The UUID for this Metadata.",
"type": "string"
},
"value": {
"description": "A free text or JSON string containing the metadata stored for the given associationIds",
"type": "string"
}
},
"required": [],
"title": "AgavePy Metadata schema",
"type": "object"
}
addSchema: Add a new Metadata Schema.¶
agavepy.meta.addSchema(body)
Parameters:¶
- body: A valid JSON Schema object (JSON, string)
Response:¶
- A single MetadataSchema object
MetadataSchema schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataSchema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata schema store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this schema.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata schema store.",
"type": "string"
},
"owner": {
"description": "The API user who owns this Schema.",
"type": "string"
},
"schema": {
"description": "A JSON Schema",
"type": "string"
},
"uuid": {
"description": "The UUID for this Schema.",
"type": "string"
}
},
"required": [],
"title": "AgavePy MetadataSchema schema",
"type": "object"
}
searchSchema: Retrieve Metadata Schemata.¶
agavepy.meta.searchSchema(uuid, limit=250, offset=0)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single MetadataSchema object
MetadataSchema schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataSchema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata schema store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this schema.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata schema store.",
"type": "string"
},
"owner": {
"description": "The API user who owns this Schema.",
"type": "string"
},
"schema": {
"description": "A JSON Schema",
"type": "string"
},
"uuid": {
"description": "The UUID for this Schema.",
"type": "string"
}
},
"required": [],
"title": "AgavePy MetadataSchema schema",
"type": "object"
}
deleteSchema: Remove Metadata Schema from the system.¶
agavepy.meta.deleteSchema(uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
Response:¶
- A single EmptyMetadata object
EmptyMetadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyMetadata.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyMetadata schema",
"type": "object"
}
getSchema: Retrieve Metadata Schemata.¶
agavepy.meta.getSchema(uuid, limit=250, offset=0)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single MetadataSchema object
MetadataSchema schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataSchema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata schema store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this schema.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata schema store.",
"type": "string"
},
"owner": {
"description": "The API user who owns this Schema.",
"type": "string"
},
"schema": {
"description": "A JSON Schema",
"type": "string"
},
"uuid": {
"description": "The UUID for this Schema.",
"type": "string"
}
},
"required": [],
"title": "AgavePy MetadataSchema schema",
"type": "object"
}
updateSchema: Update or Add a new Metadata Schema.¶
agavepy.meta.updateSchema(body, uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- body: A valid JSON Schema object (JSON, string)
Response:¶
- A single MetadataSchema object
MetadataSchema schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataSchema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"created": {
"description": "A timestamp indicating when this Metadata was created in the metadata schema store.",
"type": "string"
},
"internalUsername": {
"description": "The name of the Internal User, if any, who owns this schema.",
"type": "string"
},
"lastUpdated": {
"description": "A timestamp indicating when this Metadata was last updated in the metadata schema store.",
"type": "string"
},
"owner": {
"description": "The API user who owns this Schema.",
"type": "string"
},
"schema": {
"description": "A JSON Schema",
"type": "string"
},
"uuid": {
"description": "The UUID for this Schema.",
"type": "string"
}
},
"required": [],
"title": "AgavePy MetadataSchema schema",
"type": "object"
}
deleteMetadataPermission: Deletes all permissions on the given metadata.¶
agavepy.meta.deleteMetadataPermission(uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
Response:¶
- A single EmptyMetadata object
EmptyMetadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyMetadata.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyMetadata schema",
"type": "object"
}
listMetadataPermissions: Get the permission ACL for this metadata.¶
agavepy.meta.listMetadataPermissions(uuid, limit=250, offset=0)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of Permission objects
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
updateMetadataPermissions: Add or update a user’s permission for the given metadata.¶
agavepy.meta.updateMetadataPermissions(body, uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- body: The metadata permission to update. (JSON, MetadataPermissionRequest)
MetadataPermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataPermissionRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "The permission to set",
"enum": [
"READ",
"WRITE",
"READ_WRITE",
"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 MetadataPermissionRequest schema",
"type": "object"
}
Response:¶
- A single Permission object
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
deleteMetadataPermissionsForUser: Deletes all permissions on the given metadata.¶
agavepy.meta.deleteMetadataPermissionsForUser(username, uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- username: The username of the permission owner (string)
Response:¶
- A single EmptyMetadata object
EmptyMetadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyMetadata.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyMetadata schema",
"type": "object"
}
listMetadataPermissionsForUser: Get the permission ACL for this metadata.¶
agavepy.meta.listMetadataPermissionsForUser(username, uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- username: The username of the permission owner (string)
Response:¶
- A single Permission object
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
updateMetadataPermissionsForUser: Add or update a user’s permission for the given metadata.¶
agavepy.meta.updateMetadataPermissionsForUser(body, username, uuid)
Parameters:¶
- uuid: The uuid of the metadata item (string)
- username: The username of the permission owner (string)
- body: The metadata permission to update. (JSON, MetadataPermissionRequest)
MetadataPermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataPermissionRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "The permission to set",
"enum": [
"READ",
"WRITE",
"READ_WRITE",
"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 MetadataPermissionRequest schema",
"type": "object"
}
Response:¶
- A single Permission object
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
deleteSchemaPermissions: Deletes all permissions on the given schema.¶
agavepy.meta.deleteSchemaPermissions(uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
Response:¶
- A single EmptyMetadata object
EmptyMetadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyMetadata.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyMetadata schema",
"type": "object"
}
listSchemaPermissions: Get the permission ACL for this schema.¶
agavepy.meta.listSchemaPermissions(uuid, limit=250, offset=0)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of Permission objects
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
updateSchemaPermissions: Add or update a user’s permission for the given schema.¶
agavepy.meta.updateSchemaPermissions(body, uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- body: The schema permission to update. (JSON, MetadataPermissionRequest)
MetadataPermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataPermissionRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "The permission to set",
"enum": [
"READ",
"WRITE",
"READ_WRITE",
"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 MetadataPermissionRequest schema",
"type": "object"
}
Response:¶
- A single Permission object
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
deleteSchemaPermissionsForUser: Deletes all permissions on the given metadata.¶
agavepy.meta.deleteSchemaPermissionsForUser(username, uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- username: The username of the permission owner (string)
Response:¶
- A single EmptyMetadata object
EmptyMetadata schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyMetadata.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyMetadata schema",
"type": "object"
}
listSchemaPermissionsForUser: Get the permission ACL for this schema.¶
agavepy.meta.listSchemaPermissionsForUser(username, uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- username: The username of the permission owner (string)
Response:¶
- A single Permission object
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
updateSchemaPermissionsForUser: Add or update a user’s permission for the given metadata schema.¶
agavepy.meta.updateSchemaPermissionsForUser(body, username, uuid)
Parameters:¶
- uuid: The uuid of the metadata schema item (string)
- username: The username of the permission owner (string)
- body: The schema permission to update. (JSON, MetadataPermissionRequest)
MetadataPermissionRequest schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/MetadataPermissionRequest.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "The permission to set",
"enum": [
"READ",
"WRITE",
"READ_WRITE",
"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 MetadataPermissionRequest schema",
"type": "object"
}
Response:¶
- A single Permission object
Permission schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Permission.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permission": {
"description": "",
"type": "ACL"
},
"username": {
"description": "Username associate with this permission",
"type": "string"
}
},
"required": [],
"title": "AgavePy Permission schema",
"type": "object"
}
Notifications¶
Subscribe to and manage notification.
Notifications¶
Summary: Subscribe to and manage notifications
add: Update or Add new notification.¶
agavepy.notifications.add(body)
Parameters:¶
- 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
Notification schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Notification.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"associatedUuid": {
"description": "UUID of resource to whome the event applies.",
"type": "string"
},
"attempts": {
"description": "The number of times this notification has been attempted to be fulfilled.",
"type": "integer"
},
"created": {
"description": "A timestamp indicating when this notification was created in the notification store.",
"type": "string"
},
"lastSent": {
"description": "A timestamp indicating the last time this notification was sent.",
"type": "string"
},
"owner": {
"description": "The API user who owns this notification.",
"type": "string"
},
"persistent": {
"description": "Whether this notification should stay active after it fires the first time.",
"type": "boolean"
},
"responseCode": {
"description": "The response code from POSTing to the url or sending an email.",
"type": "integer"
},
"success": {
"description": "Whether this notification was sent successfully.",
"type": "boolean"
},
"url": {
"description": "The url or email address that will be notified of the event.",
"type": "string"
},
"uuid": {
"description": "The UUID for this notification.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Notification schema",
"type": "object"
}
list: Retrieve notification for a specific resource.¶
agavepy.notifications.list(associatedUuid=None, limit=250, offset=0)
Parameters:¶
- associatedUuid: The uuid of the associated resource. All notifications for this resource visible to the user will be returned. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of Notification objects
Notification schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Notification.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"associatedUuid": {
"description": "UUID of resource to whome the event applies.",
"type": "string"
},
"attempts": {
"description": "The number of times this notification has been attempted to be fulfilled.",
"type": "integer"
},
"created": {
"description": "A timestamp indicating when this notification was created in the notification store.",
"type": "string"
},
"lastSent": {
"description": "A timestamp indicating the last time this notification was sent.",
"type": "string"
},
"owner": {
"description": "The API user who owns this notification.",
"type": "string"
},
"persistent": {
"description": "Whether this notification should stay active after it fires the first time.",
"type": "boolean"
},
"responseCode": {
"description": "The response code from POSTing to the url or sending an email.",
"type": "integer"
},
"success": {
"description": "Whether this notification was sent successfully.",
"type": "boolean"
},
"url": {
"description": "The url or email address that will be notified of the event.",
"type": "string"
},
"uuid": {
"description": "The UUID for this notification.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Notification schema",
"type": "object"
}
delete: Remove notification from the system.¶
agavepy.notifications.delete(uuid)
Parameters:¶
- uuid: The uuid of the notification item (string)
Response:¶
- A single EmptyNotification object
EmptyNotification schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/EmptyNotification.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"required": [],
"title": "AgavePy EmptyNotification schema",
"type": "object"
}
get: Retrieve notification.¶
agavepy.notifications.get(uuid)
Parameters:¶
- uuid: The uuid of the notification item (string)
Response:¶
- A single Notification object
Notification schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Notification.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"associatedUuid": {
"description": "UUID of resource to whome the event applies.",
"type": "string"
},
"attempts": {
"description": "The number of times this notification has been attempted to be fulfilled.",
"type": "integer"
},
"created": {
"description": "A timestamp indicating when this notification was created in the notification store.",
"type": "string"
},
"lastSent": {
"description": "A timestamp indicating the last time this notification was sent.",
"type": "string"
},
"owner": {
"description": "The API user who owns this notification.",
"type": "string"
},
"persistent": {
"description": "Whether this notification should stay active after it fires the first time.",
"type": "boolean"
},
"responseCode": {
"description": "The response code from POSTing to the url or sending an email.",
"type": "integer"
},
"success": {
"description": "Whether this notification was sent successfully.",
"type": "boolean"
},
"url": {
"description": "The url or email address that will be notified of the event.",
"type": "string"
},
"uuid": {
"description": "The UUID for this notification.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Notification schema",
"type": "object"
}
update: Update or Add new notification.¶
agavepy.notifications.update(body, uuid)
Parameters:¶
- uuid: The uuid of the notification item (string)
- body: The notification to update. (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
Notification schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Notification.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"associatedUuid": {
"description": "UUID of resource to whome the event applies.",
"type": "string"
},
"attempts": {
"description": "The number of times this notification has been attempted to be fulfilled.",
"type": "integer"
},
"created": {
"description": "A timestamp indicating when this notification was created in the notification store.",
"type": "string"
},
"lastSent": {
"description": "A timestamp indicating the last time this notification was sent.",
"type": "string"
},
"owner": {
"description": "The API user who owns this notification.",
"type": "string"
},
"persistent": {
"description": "Whether this notification should stay active after it fires the first time.",
"type": "boolean"
},
"responseCode": {
"description": "The response code from POSTing to the url or sending an email.",
"type": "integer"
},
"success": {
"description": "Whether this notification was sent successfully.",
"type": "boolean"
},
"url": {
"description": "The url or email address that will be notified of the event.",
"type": "string"
},
"uuid": {
"description": "The UUID for this notification.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Notification schema",
"type": "object"
}
Profiles¶
Create and manage application users (profiles).
Profiles¶
Summary: Create and manage application users
list: List user profiles¶
agavepy.profiles.list(email=None, first_name=None, full_name=None, last_name=None, limit=250, name=None, offset=0, status=None, username=None)
Parameters:¶
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
- name: Filter results by name. (string)
- email: Filter results by email. (string)
- first_name: Filter results by first_name. (string)
- last_name: Filter results by last_name. (string)
- full_name: Filter results by full_name. (string)
- status: Filter results by status. (string)
- username: Filter results by username. (string)
Response:¶
- Array of Profile objects
Profile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Profile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"city": {
"description": "The api user's city.",
"type": "string"
},
"country": {
"description": "The api user's country.",
"type": "string"
},
"department": {
"description": "The api user's institutional department.",
"type": "string"
},
"email": {
"description": "The api user's unique email address.",
"type": "string"
},
"fax": {
"description": "The api user's fax number.",
"type": "string"
},
"firstName": {
"description": "The api user's first name.",
"type": "string"
},
"gender": {
"description": "The api user's gender. male or female.",
"type": "string"
},
"institution": {
"description": "The api user's home institution",
"type": "string"
},
"lastName": {
"description": "The api user's last name.",
"type": "string"
},
"phone": {
"description": "The api user's phone number.",
"type": "string"
},
"position": {
"description": "The api user's position of employment.",
"type": "string"
},
"researchArea": {
"description": "The api user's primary area of research.",
"type": "string"
},
"state": {
"description": "The api user's state.",
"type": "string"
},
"username": {
"description": "The api user's unique username.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Profile schema",
"type": "object"
}
get: Find authenticated user profile¶
agavepy.profiles.get()
Parameters:¶
Response:¶
- A single Profile object
Profile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Profile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"city": {
"description": "The api user's city.",
"type": "string"
},
"country": {
"description": "The api user's country.",
"type": "string"
},
"department": {
"description": "The api user's institutional department.",
"type": "string"
},
"email": {
"description": "The api user's unique email address.",
"type": "string"
},
"fax": {
"description": "The api user's fax number.",
"type": "string"
},
"firstName": {
"description": "The api user's first name.",
"type": "string"
},
"gender": {
"description": "The api user's gender. male or female.",
"type": "string"
},
"institution": {
"description": "The api user's home institution",
"type": "string"
},
"lastName": {
"description": "The api user's last name.",
"type": "string"
},
"phone": {
"description": "The api user's phone number.",
"type": "string"
},
"position": {
"description": "The api user's position of employment.",
"type": "string"
},
"researchArea": {
"description": "The api user's primary area of research.",
"type": "string"
},
"state": {
"description": "The api user's state.",
"type": "string"
},
"username": {
"description": "The api user's unique username.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Profile schema",
"type": "object"
}
listByUsername: Find api user profile by their api username¶
agavepy.profiles.listByUsername(username)
Parameters:¶
- username: The username of a valid api user (string)
Response:¶
- A single Profile object
Profile schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Profile.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"city": {
"description": "The api user's city.",
"type": "string"
},
"country": {
"description": "The api user's country.",
"type": "string"
},
"department": {
"description": "The api user's institutional department.",
"type": "string"
},
"email": {
"description": "The api user's unique email address.",
"type": "string"
},
"fax": {
"description": "The api user's fax number.",
"type": "string"
},
"firstName": {
"description": "The api user's first name.",
"type": "string"
},
"gender": {
"description": "The api user's gender. male or female.",
"type": "string"
},
"institution": {
"description": "The api user's home institution",
"type": "string"
},
"lastName": {
"description": "The api user's last name.",
"type": "string"
},
"phone": {
"description": "The api user's phone number.",
"type": "string"
},
"position": {
"description": "The api user's position of employment.",
"type": "string"
},
"researchArea": {
"description": "The api user's primary area of research.",
"type": "string"
},
"state": {
"description": "The api user's state.",
"type": "string"
},
"username": {
"description": "The api user's unique username.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Profile schema",
"type": "object"
}
Actors¶
Agave actors are based off the actor model. Actors are meant to respond to messages from the user or from thrid-party applications and act in the user’s interest be it by creating other actors, running Agave applications, moving data, etc.
For more info on how actors are implemented see TACC/abaco.
Actors¶
Summary: Create and manage actors.
add: Register an actor.¶
agavepy.actors.add(body)
Parameters:¶
- 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
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"
}
list: List actors¶
agavepy.actors.list(limit=250, offset=0)
Parameters:¶
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- Array of Actor objects
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"
}
delete: Delete a specific actor.¶
agavepy.actors.delete(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- A single String object
get: Retrieve details about a specific actor.¶
agavepy.actors.get(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- A single Actor object
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"
}
update: Retrieve details about a specific actor.¶
agavepy.actors.update(actorId, body)
Parameters:¶
- 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
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"
}
getMessages: Get the current number of messages for an actor.¶
agavepy.actors.getMessages(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- A single ActorMessages object
ActorMessages schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorMessages.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"messages": {
"description": "The number of messages waiting in queue to be processed by this actor.",
"type": "int"
}
},
"required": [],
"title": "AgavePy ActorMessages schema",
"type": "object"
}
sendBinaryMessage: Send a message to an actor mailbox.¶
agavepy.actors.sendBinaryMessage(actorId, message, environment=None)
Parameters:¶
- actorId: The id of the actor. (string)
- environment: Optional dictionary of environmental variables (dict)
- 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.¶
agavepy.actors.sendMessage(actorId, body, environment=None)
Parameters:¶
- actorId: The id of the actor. (string)
- environment: Optional dictionary of environmental variables (dict)
- body: 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
getState: Get the current state for an actor.¶
agavepy.actors.getState(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- A single ActorState object
ActorState schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorState.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"state": {
"description": "The current state of the actor.",
"type": "string"
}
},
"required": [],
"title": "AgavePy ActorState schema",
"type": "object"
}
updateState: Update an actor’s state with a JSON-serializable object.¶
agavepy.actors.updateState(actorId, body)
Parameters:¶
- actorId: The id of the actor. (string)
- body: The value of the state. Should be JSON-serializable. (JSON, string)
Response:¶
- A single ActorState object
ActorState schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorState.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"state": {
"description": "The current state of the actor.",
"type": "string"
}
},
"required": [],
"title": "AgavePy ActorState schema",
"type": "object"
}
getPermissions: Get the current permissions for an actor.¶
agavepy.actors.getPermissions(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- A single ActorPermissions object
ActorPermissions schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorPermissions.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"permissions": {
"description": "The dictionary of permissions associated with the actor.",
"type": "string"
}
},
"required": [],
"title": "AgavePy ActorPermissions schema",
"type": "object"
}
updatePermissions: Update an actor’s permissions with a new permission for a user.¶
agavepy.actors.updatePermissions(actorId, body)
Parameters:¶
- 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.¶
agavepy.actors.addWorker(actorId, body)
Parameters:¶
- 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.¶
agavepy.actors.listWorkers(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- Array of ActorWorker objects
ActorWorker schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorWorker.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cid": {
"description": "Container id of this worker.",
"type": "string"
},
"host_id": {
"description": "id of the host where this worker is running.",
"type": "string"
},
"host_ip": {
"description": "IP address of the host where this worker is running.",
"type": "string"
},
"id": {
"description": "The unique id of this worker.",
"type": "string"
},
"image": {
"description": "Docker image associated with the actor.",
"type": "string"
},
"last_execution": {
"description": "Last execution for this worker.",
"type": "int"
},
"location": {
"description": "Location of docker daemon that this worker is using.",
"type": "string"
},
"status": {
"description": "status of the worker.",
"type": "string"
},
"tenant": {
"description": "tenant this worker belongs to.",
"type": "string"
}
},
"required": [],
"title": "AgavePy ActorWorker schema",
"type": "object"
}
deleteWorker: Delete a worker.¶
agavepy.actors.deleteWorker(actorId, workerId)
Parameters:¶
- 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.¶
agavepy.actors.getWorker(actorId, workerId)
Parameters:¶
- actorId: The id of the actor. (string)
- workerId: The id of the worker. (string)
Response:¶
- A single ActorWorker object
ActorWorker schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorWorker.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cid": {
"description": "Container id of this worker.",
"type": "string"
},
"host_id": {
"description": "id of the host where this worker is running.",
"type": "string"
},
"host_ip": {
"description": "IP address of the host where this worker is running.",
"type": "string"
},
"id": {
"description": "The unique id of this worker.",
"type": "string"
},
"image": {
"description": "Docker image associated with the actor.",
"type": "string"
},
"last_execution": {
"description": "Last execution for this worker.",
"type": "int"
},
"location": {
"description": "Location of docker daemon that this worker is using.",
"type": "string"
},
"status": {
"description": "status of the worker.",
"type": "string"
},
"tenant": {
"description": "tenant this worker belongs to.",
"type": "string"
}
},
"required": [],
"title": "AgavePy ActorWorker schema",
"type": "object"
}
addNonce: Add a nonce to an actor.¶
agavepy.actors.addNonce(actorId, body=)
Parameters:¶
- actorId: The id of the actor. (string)
- body: The description of the nonce to add. (JSON, AddNonceRequest)
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.¶
agavepy.actors.listNonces(actorId)
Parameters:¶
- actorId: The id of the actor. (string)
Response:¶
- Array of ActorNonce objects
ActorNonce schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorNonce.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actor_id": {
"description": "Actor id associated with nonce.",
"type": "string"
},
"create_time": {
"description": "Time stamp when nonce was created.",
"type": "string"
},
"id": {
"description": "The unique id of the nonce.",
"type": "string"
},
"last_use_time": {
"description": "Last time nonce was used.",
"type": "string"
},
"level": {
"description": "Permission level associated with nonce.",
"type": "string"
},
"max_uses": {
"description": "Max number of uses for this nonce.",
"type": "string"
},
"remaining_uses": {
"description": "Remaining uses of nonce.",
"type": "int"
}
},
"required": [],
"title": "AgavePy ActorNonce schema",
"type": "object"
}
deleteNonce: Delete a nonce.¶
agavepy.actors.deleteNonce(actorId, nonceId)
Parameters:¶
- 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.¶
agavepy.actors.getNonce(actorId, nonceId)
Parameters:¶
- actorId: The id of the actor. (string)
- nonceId: The id of the nonce. (string)
Response:¶
- A single ActorNonce object
ActorNonce schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ActorNonce.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actor_id": {
"description": "Actor id associated with nonce.",
"type": "string"
},
"create_time": {
"description": "Time stamp when nonce was created.",
"type": "string"
},
"id": {
"description": "The unique id of the nonce.",
"type": "string"
},
"last_use_time": {
"description": "Last time nonce was used.",
"type": "string"
},
"level": {
"description": "Permission level associated with nonce.",
"type": "string"
},
"max_uses": {
"description": "Max number of uses for this nonce.",
"type": "string"
},
"remaining_uses": {
"description": "Remaining uses of nonce.",
"type": "int"
}
},
"required": [],
"title": "AgavePy ActorNonce schema",
"type": "object"
}
listExecutions: Summary data of all actor executions.¶
agavepy.actors.listExecutions(actorId, limit=250, offset=0)
Parameters:¶
- actorId: The id of the actor. (string)
- limit: The max number of results. (integer)
- offset: The number of records to when returning the results. When paginating results, the page number = ceil(offset/limit) (integer)
Response:¶
- A single ExecutionsSummary object
ExecutionsSummary schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ExecutionsSummary.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actorId": {
"description": "The id of the associated actor.",
"type": "string"
},
"ids": {
"description": "The ids of all executions.",
"type": "array"
},
"owner": {
"description": "username of the owner of the actor.",
"type": "string"
},
"totalCpu": {
"description": "CPU usage, in user jiffies, of all executions.",
"type": "int"
},
"totalIo": {
"description": "Block I/O usage, in number of 512-byte sectors read from and written to, by all executions.",
"type": "int"
},
"totalRuntime": {
"description": "Runtime, in milliseconds, of all executions.",
"type": "int"
}
},
"required": [],
"title": "AgavePy ExecutionsSummary schema",
"type": "object"
}
getExecution: Retrieve details about a specific actor execution.¶
agavepy.actors.getExecution(actorId, executionId)
Parameters:¶
- actorId: The id of the actor. (string)
- executionId: The id of the execution. (string)
Response:¶
- A single Execution object
Execution schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/Execution.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"actorId": {
"description": "The id of the associated actor.",
"type": "string"
},
"cpu": {
"description": "CPU usage, in user jiffies, of this execution.",
"type": "int"
},
"id": {
"description": "The id of this executions.",
"type": "string"
},
"io": {
"description": "Block I/O usage, in number of 512-byte sectors read from and written to, by this execution.",
"type": "int"
},
"owner": {
"description": "username of the owner of the actor.",
"type": "string"
},
"runtime": {
"description": "Runtime, in milliseconds, of this execution.",
"type": "int"
},
"status": {
"description": "status of the execution.",
"type": "string"
}
},
"required": [],
"title": "AgavePy Execution schema",
"type": "object"
}
getOneExecutionResult: Get result for a specific actor execution.¶
agavepy.actors.getOneExecutionResult(actorId, executionId)
Parameters:¶
- actorId: The id of the actor. (string)
- executionId: The id of the execution. (string)
Response:¶
- None
getExecutionLogs: Get logs for a specific actor execution.¶
agavepy.actors.getExecutionLogs(actorId, executionId)
Parameters:¶
- actorId: The id of the actor. (string)
- executionId: The id of the execution. (string)
Response:¶
- A single ExecutionLogs object
ExecutionLogs schema
{
"$id": "http://agavepy.readthedocs.io/en/latest/ExecutionLogs.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"logs": {
"description": "The logs (standard out) of this execution.",
"type": "string"
}
},
"required": [],
"title": "AgavePy ExecutionLogs schema",
"type": "object"
}