Warning

This document is for an in-development version of Galaxy. You can alternatively view this page in the latest release if it exists or view the top of the latest release's documentation.

Tool Shed API

tool_shed.webapp.api.authenticate module

API key retrieval through BaseAuth Sample usage:

curl –user zipzap@foo.com:password http://localhost:9009/api/authenticate/baseauth

Returns: {

“api_key”: <some api key>

}

class tool_shed.webapp.api.authenticate.ToolShedAuthenticationController(app)

Bases: galaxy.webapps.galaxy.api.authenticate.AuthenticationController

get_tool_shed_api_key(trans, **kwd)

def get_api_key( self, trans, **kwd ) * GET /api/authenticate/baseauth returns an API key for authenticated user based on BaseAuth headers

Returns:api_key in json format Return type:dict Raises:ObjectNotFound, HTTPBadRequest

tool_shed.webapp.api.categories module

class tool_shed.webapp.api.categories.CategoriesController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

RESTful controller for interactions with categories in the Tool Shed.

create(trans, payload, **kwd)

POST /api/categories Return a dictionary of information about the created category. The following parameters are included in the payload:

Parameters:

• (required) (name) – the name of the category
• (optional) (description) – the description of the category (if not provided, the name will be used)

Example: POST /api/categories/?key=XXXYYYXXXYYY Content-Disposition: form-data; name=”name” Category_Name Content-Disposition: form-data; name=”description” Category_Description

get_repositories(trans, category_id, **kwd)

GET /api/categories/{encoded_category_id}/repositories Return information about the provided category and the repositories in that category.

Parameters:

• id – the encoded id of the Category object
• sort_key – the field by which the repositories should be sorted
• sort_order – ascending or descending sort
• page – the page number to return

Example: GET localhost:9009/api/categories/f9cad7b01a472135/repositories

index(trans, deleted=False, **kwd)

GET /api/categories Return a list of dictionaries that contain information about each Category.

Parameters:deleted – flag used to include deleted categories

Example: GET localhost:9009/api/categories

show(trans, id, **kwd)

GET /api/categories/{encoded_category_id} Return a dictionary of information about a category.

Parameters:id – the encoded id of the Category object

Example: GET localhost:9009/api/categories/f9cad7b01a472135

tool_shed.webapp.api.configuration module

API operations allowing clients to determine Tool Shed instance’s capabilities and configuration settings.

class tool_shed.webapp.api.configuration.ConfigurationController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

__init__(app)

version(trans, **kwds)

GET /api/version Return a description of the version_major and version of Galaxy Tool Shed (e.g. 15.07 and 15.07.dev).

Return type:dict Returns:dictionary with versions keyed as ‘version_major’ and ‘version’

tool_shed.webapp.api.groups module

class tool_shed.webapp.api.groups.GroupsController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

RESTful controller for interactions with groups in the Tool Shed.

__init__(app)

index(trans, deleted=False, **kwd)

GET /api/groups Return a list of dictionaries that contain information about each Group.

Parameters:deleted – flag used to include deleted groups

Example: GET localhost:9009/api/groups

create(trans, payload, **kwd)

POST /api/groups Return a dictionary of information about the created group. The following parameters are included in the payload:

Parameters:

• (required) (name) – the name of the group
• (optional) (description) – the description of the group

Example: POST /api/groups/?key=XXXYYYXXXYYY Content-Disposition: form-data; name=”name” Group_Name Content-Disposition: form-data; name=”description” Group_Description

show(trans, encoded_id, **kwd)

GET /api/groups/{encoded_group_id} Return a dictionary of information about a group.

Parameters:id – the encoded id of the Group object

Example: GET localhost:9009/api/groups/f9cad7b01a472135

tool_shed.webapp.api.repositories module

class tool_shed.webapp.api.repositories.RepositoriesController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

RESTful controller for interactions with repositories in the Tool Shed.

add_repository_registry_entry(trans, payload, **kwd)

POST /api/repositories/add_repository_registry_entry Adds appropriate entries to the repository registry for the repository defined by the received name and owner.

Parameters:key – the user’s API key

The following parameters are included in the payload. :param tool_shed_url (required): the base URL of the Tool Shed containing the Repository :param name (required): the name of the Repository :param owner (required): the owner of the Repository

get_ordered_installable_revisions(trans, name=None, owner=None, **kwd)

GET /api/repositories/get_ordered_installable_revisions

Parameters:

• name – the name of the Repository
• owner – the owner of the Repository

Returns the ordered list of changeset revision hash strings that are associated with installable revisions. As in the changelog, the list is ordered oldest to newest.

get_repository_revision_install_info(trans, name, owner, changeset_revision, **kwd)

GET /api/repositories/get_repository_revision_install_info

Parameters:

• name – the name of the Repository
• owner – the owner of the Repository
• changeset_revision – the changeset_revision of the RepositoryMetadata object associated with the Repository

Returns a list of the following dictionaries:: - a dictionary defining the Repository. For example: {

“deleted”: false, “deprecated”: false, “description”: “add_column hello”, “id”: “f9cad7b01a472135”, “long_description”: “add_column hello”, “name”: “add_column”, “owner”: “test”, “private”: false, “times_downloaded”: 6, “url”: “/api/repositories/f9cad7b01a472135”, “user_id”: “f9cad7b01a472135”

} - a dictionary defining the Repository revision (RepositoryMetadata). For example: {

“changeset_revision”: “3a08cc21466f”, “downloadable”: true, “has_repository_dependencies”: false, “has_repository_dependencies_only_if_compiling_contained_td”: false, “id”: “f9cad7b01a472135”, “includes_datatypes”: false, “includes_tool_dependencies”: false, “includes_tools”: true, “includes_tools_for_display_in_tool_panel”: true, “includes_workflows”: false, “malicious”: false, “repository_id”: “f9cad7b01a472135”, “url”: “/api/repository_revisions/f9cad7b01a472135”, “valid_tools”: [{u’add_to_tool_panel’: True,

u’description’: u’data on any column using simple expressions’, u’guid’: u’localhost:9009/repos/enis/sample_repo_1/Filter1/2.2.0’, u’id’: u’Filter1’, u’name’: u’Filter’, u’requirements’: [], u’tests’: [{u’inputs’: [[u’input’, u’1.bed’], [u’cond’, u”c1==’chr22’”]],

u’name’: u’Test-1’, u’outputs’: [[u’out_file1’, u’filter1_test1.bed’]], u’required_files’: [u’1.bed’, u’filter1_test1.bed’]}],

u’tool_config’: u’database/community_files/000/repo_1/filtering.xml’, u’tool_type’: u’default’, u’version’: u’2.2.0’, u’version_string_cmd’: None}]

} - a dictionary including the additional information required to install the repository. For example: {

“add_column”: [

“add_column hello”, “http://test@localhost:9009/repos/test/add_column”, “3a08cc21466f”, “1”, “test”, {}, {}

]

}

get_installable_revisions(trans, **kwd)

GET /api/repositories/get_installable_revisions

Parameters:tsr_id – the encoded toolshed ID of the repository

Returns a list of lists of changesets, in the format [ [ 0, fbb391dc803c ], [ 1, 9d9ec4d9c03e ], [ 2, 9b5b20673b89 ], [ 3, e8c99ce51292 ] ].

index(trans, deleted=False, owner=None, name=None, **kwd)

GET /api/repositories Displays a collection of repositories with optional criteria.

Parameters:

• q (str) – (optional)if present search on the given query will be performed
• page (int) – (optional)requested page of the search
• page_size (int) – (optional)requested page_size of the search
• jsonp (bool) – (optional)flag whether to use jsonp format response, defaults to False
• callback (str) – (optional)name of the function to wrap callback in used only when jsonp is true, defaults to ‘callback’
• deleted (bool) – (optional)displays repositories that are or are not set to deleted.
• owner (str) – (optional)the owner’s public username.
• name (str) – (optional)the repository name.
• tool_ids – (optional) a tool GUID to find the repository for
• tool_ids – str

Returns dict:

object containing list of results

Examples:

GET http://localhost:9009/api/repositories GET http://localhost:9009/api/repositories?q=fastq

remove_repository_registry_entry(trans, payload, **kwd)

POST /api/repositories/remove_repository_registry_entry Removes appropriate entries from the repository registry for the repository defined by the received name and owner.

Parameters:key – the user’s API key

The following parameters are included in the payload. :param tool_shed_url (required): the base URL of the Tool Shed containing the Repository :param name (required): the name of the Repository :param owner (required): the owner of the Repository

repository_ids_for_setting_metadata(trans, my_writable=False, **kwd)

GET /api/repository_ids_for_setting_metadata

Displays a collection (list) of repository ids ordered for setting metadata.

Parameters:

• key – the API key of the Tool Shed user.
• (optional) (my_writable) – if the API key is associated with an admin user in the Tool Shed, setting this param value to True will restrict resetting metadata to only repositories that are writable by the user in addition to those repositories of type tool_dependency_definition. This param is ignored if the current user is not an admin user, in which case this same restriction is automatic.

reset_metadata_on_repositories(trans, payload, **kwd)

PUT /api/repositories/reset_metadata_on_repositories

Resets all metadata on all repositories in the Tool Shed in an “orderly fashion”. Since there are currently only two repository types (tool_dependecy_definition and unrestricted), the order in which metadata is reset is repositories of type tool_dependecy_definition first followed by repositories of type unrestricted, and only one pass is necessary. If a new repository type is introduced, the process will undoubtedly need to be revisited. To facilitate this order, an in-memory list of repository ids that have been processed is maintained.

Parameters:key – the API key of the Tool Shed user.

The following parameters can optionally be included in the payload. :param my_writable (optional): if the API key is associated with an admin user in the Tool Shed, setting this param value

to True will restrict resetting metadata to only repositories that are writable by the user in addition to those repositories of type tool_dependency_definition. This param is ignored if the current user is not an admin user, in which case this same restriction is automatic.

Parameters:

• (optional) (skip_file) – a list of encoded repository ids for repositories that should not be processed.
• (optional) – A local file name that contains the encoded repository ids associated with repositories to skip. This param can be used as an alternative to the above encoded_ids_to_skip.

reset_metadata_on_repository(trans, payload, **kwd)

PUT /api/repositories/reset_metadata_on_repository

Resets all metadata on a specified repository in the Tool Shed.

Parameters:key – the API key of the Tool Shed user.

The following parameters must be included in the payload. :param repository_id: the encoded id of the repository on which metadata is to be reset.

show(trans, id, **kwd)

GET /api/repositories/{encoded_repository_id} Returns information about a repository in the Tool Shed.

Example URL: http://localhost:9009/api/repositories/f9cad7b01a472135

Parameters:id (encoded str) – the encoded id of the Repository object Returns:detailed repository information Return type:dict Raises:ObjectNotFound, MalformedId

updates(trans, **kwd)

GET /api/repositories/updates Return a dictionary with boolean values for whether there are updates available for the repository revision, newer installable revisions available, the revision is the latest installable revision, and if the repository is deprecated.

Parameters:

• owner (str) – owner of the repository
• name (str) – name of the repository
• changeset_revision (str) – changeset of the repository
• hexlify – flag whether to hexlify the response (for backward compatibility)

Returns:

information about repository deprecations, updates, and upgrades

Return type:

dict

show_tools(trans, id, changeset, **kwd)

metadata(trans, id, **kwd)

GET /api/repositories/{encoded_repository_id}/metadata Returns information about a repository in the Tool Shed.

Example URL: http://localhost:9009/api/repositories/f9cad7b01a472135/metadata

Parameters:id – the encoded id of the Repository object Returns:A dictionary containing the specified repository’s metadata, by changeset, recursively including dependencies and their metadata. Not found:Empty dictionary.

update(trans, id, **kwd)

PATCH /api/repositories/{encoded_repository_id} Updates information about a repository in the Tool Shed.

Parameters:

• id – the encoded id of the Repository object
• payload (dict) –

  dictionary structure containing:: ‘name’: repo’s name (optional) ‘synopsis’: repo’s synopsis (optional) ‘description’: repo’s description (optional) ‘remote_repository_url’: repo’s remote repo (optional) ‘homepage_url’: repo’s homepage url (optional) ‘category_ids’: list of existing encoded TS category ids

  the updated repo should be associated with (optional)

Returns:

detailed repository information

Return type:

dict

Raises:

RequestParameterInvalidException, InsufficientPermissionsException

create(self, trans, payload, **kwd)

• POST /api/repositories:

  Creates a new repository. Only name and synopsis parameters are required.

Parameters:payload (dict) –

dictionary structure containing:: ‘name’: new repo’s name (required) ‘synopsis’: new repo’s synopsis (required) ‘description’: new repo’s description (optional) ‘remote_repository_url’: new repo’s remote repo (optional) ‘homepage_url’: new repo’s homepage url (optional) ‘category_ids[]’: list of existing encoded TS category ids

the new repo should be associated with (optional)

’type’: new repo’s type, defaults to unrestricted (optional)

Returns:detailed repository information Return type:dict Raises:RequestParameterMissingException, RequestParameterInvalidException

create_changeset_revision(trans, id, payload, **kwd)

POST /api/repositories/{encoded_repository_id}/changeset_revision

Create a new tool shed repository commit - leaving PUT on parent resource open for updating meta-attributes of the repository (and Galaxy doesn’t allow PUT multipart data anyway https://trello.com/c/CQwmCeG6).

Parameters:id – the encoded id of the Repository object

The following parameters may be included in the payload. :param commit_message: hg commit message for update.

tool_shed.webapp.api.repository_revisions module

class tool_shed.webapp.api.repository_revisions.RepositoryRevisionsController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

RESTful controller for interactions with tool shed repository revisions.

index(trans, **kwd)

GET /api/repository_revisions Displays a collection (list) of repository revisions.

repository_dependencies(trans, id, **kwd)

GET /api/repository_revisions/{encoded repository_metadata id}/repository_dependencies

Returns a list of dictionaries that each define a specific downloadable revision of a repository in the Tool Shed. This method returns dictionaries with more information in them than other methods in this controller. The information about repository_metdata is enhanced to include information about the repository (e.g., name, owner, etc) associated with the repository_metadata record.

Parameters:id – the encoded id of the RepositoryMetadata object

show(trans, id, **kwd)

GET /api/repository_revisions/{encoded_repository_metadata_id} Displays information about a repository_metadata record in the Tool Shed.

Parameters:id – the encoded id of the RepositoryMetadata object

update(trans, payload, **kwd)

PUT /api/repository_revisions/{encoded_repository_metadata_id}/{payload} Updates the value of specified columns of the repository_metadata table based on the key / value pairs in payload.

Parameters:id – the encoded id of the RepositoryMetadata object

tool_shed.webapp.api.tools module

class tool_shed.webapp.api.tools.ToolsController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

RESTful controller for interactions with tools in the Tool Shed.

index(trans, **kwd)

GET /api/tools Displays a collection of tools with optional criteria.

Parameters:

• q (str) – (optional)if present search on the given query will be performed
• page (int) – (optional)requested page of the search
• page_size (int) – (optional)requested page_size of the search
• jsonp (bool) – (optional)flag whether to use jsonp format response, defaults to False
• callback (str) – (optional)name of the function to wrap callback in used only when jsonp is true, defaults to ‘callback’

Returns dict:

object containing list of results and metadata

Examples:

GET http://localhost:9009/api/tools GET http://localhost:9009/api/tools?q=fastq

json(trans, **kwd)

GET /api/tools/json

Get the tool form JSON for a tool in a repository.

Parameters:

• guid – the GUID of the tool
• guid – str
• tsr_id – the ID of the repository
• tsr_id – str
• changeset – the changeset at which to load the tool json
• changeset – str

tool_shed.webapp.api.users module

class tool_shed.webapp.api.users.UsersController(app)

Bases: galaxy.webapps.base.controller.BaseAPIController

RESTful controller for interactions with users in the Tool Shed.

create(trans, payload, **kwd)

POST /api/users Returns a dictionary of information about the created user.

: param key: the current Galaxy admin user’s API key

The following parameters are included in the payload. :param email (required): the email address of the user :param password (required): the password of the user :param username (required): the public username of the user

index(trans, deleted=False, **kwd)

GET /api/users Returns a list of dictionaries that contain information about each user.

show(trans, id, **kwd)

GET /api/users/{encoded_user_id} GET /api/users/current Returns a dictionary of information about a user.

Parameters:id – the encoded id of the User object.