Gemma REST API interactive documen­tation

Welcome

This website documents the usage of the Gemma REST API. Here you can find example script usage of the API, as well as graphical interface for each endpoint, with description of its parameters and the endpoint URL.

The documentation of the underlying java code can be found here. See the links section in the footer of this page for other relevant links.

Use of this webpage and Gemma web services, including the REST API, is subject to these terms and conditions. Please read these in full before continuing to use this webpage or any other part of the Gemma system.

Updates

Update 2.3.4

November 6th, 2018

November 6th [2.3.4] Bug fixes in the dataset search endpoint.

November 5th [2.3.3] Added filtering parameters to dataset search.

October 25th [2.3.2] Changed behavior of the dataset search endpoint to more closely match the Gemma web interface.

October 2nd [2.3.1] Added group information to the User value object.

September 27th [2.3.0] Breaking change in Taxa: Abbreviation property has been removed and is therefore no longer an accepted identifier.

Update 2.2.6

June 7th, 2018

Code maintenance, bug fixes. Geeq scores stable and made public.

June 7th [2.2.6] Added: User authentication endpoint.

May 2nd [2.2.5] Fixed: Cleaned up and optimized platforms/elements endpoint, removed redundant information (recursive properties nesting).

April 12th [2.2.3] Fixed: Array arguments not handling non-string properties properly, e.g. ncbiIds of genes.

April 9th [2.2.1] Fixed: Filter argument not working when the filtered field was a primitive type. This most significantly allows filtering by geeq boolean and double properties.


Update 2.2.0

February 8th, 2018

Breaking change in the 'Dataset differential analysis' endpoint:

[Experimental] Added Geeq (Gene Expression Experiment Quality) scores to the dataset value objects


Update 2.1.1

December 5th, 2017

Added the 'Dataset SVD Information' Endpoint.


Update 2.1.0 (Public stable release)

November 28th, 2017

Breaking change in all endpoints that use the ExpressionExperimentValueObject in the response (mainly Datasets, Dataset search, Platforms datasets). The structure of the value object has changed - removed unused properties (moved to ExpressionExperimentDetailsValueObject, which not used in the API)

Breaking changes in 'Dataset genes expression levels' endpoint:

Added Basic Authentication.

Fixed: The 'Short Name' identifier for datasets not allowing hyphens.


Versions prior to this release were considered experimental (beta - minor version not bumped on breaking changes).


Update 2.0.5

November 28th, 2017

Fixed: gene coexpression endpoint not working.

Fixed: Multiple ontology term URIs not being parsed properly in search endpoints.

Fixed: Problems when some parameters contained unescaped forward slashes

Fixed: Taxon array arguments not working if the first identifier was not found.

Fixed: NPEs on various occasions.


Update 2.0.4

October 30th, 2017

Breaking change: Use FactorValueBasicValueObject in 'Dataset samples' endpoint.

Added 'Datasets genes expression levels' endpoint.

Added 'Datasets pca component expression levels' endpoint.

Added 'Datasets differential expression levels' endpoint.

Improved unrecognized identifier error message.


Update 2.0.3

October 18th, 2017

Breaking change: Removed 'specific x' endpoints - replaced with 'all x' endpoints using array arguments.

Breaking change: Add array arguments to 'Platform elements' and 'Genes' endpoints.

Breaking change: Change 'Dataset search' endpoint URI to use 'datasets' instead of 'experiments'

Fixed: limit 0 causing 0 results instead of not limiting the response size in some endpoints.


Update 2.0.2

October 18th, 2017

Breaking change: Add array arguments, add listed datasets endpoint.

Added NCBI ID as a possible Taxon identifier.

Added optional tree parameter to the 'Taxon phenotypes' endpoint.

Added 'Taxon phenotypes candidate genes' endpoint.


Update 2.0.1

September 22nd, 2017

Fixed: Various NPEs and small problems.


Update 2.0-Beta

August 16th, 2017

Public beta release.

Code samples

Examples of the API usage in scripts.

R
                                    {{ rExample }}
                                

R package

For the R language, it is best to use the gemmaAPI.R wrapper package . Please follow the link for documentation on how to use it. The above code example is connecting directly to the API without the use of the package.

Python
                                    {{ pythonExample }}
                                

API Endpoints

Below is a list of all API endpoints, with a GUI for test calls.

Click on the endpoint category to expand it, and then on each endpoint name to see its interface and parameters.

To display information about any parameter, click the button next to the parameter field.

Response format

The default format of the response is JSON. Some endpoints return text files or tar.gz archives - Your browser or pop up blockers might prevent these files from being downloaded, make sure you allow pop ups on this webpage.

For successful api calls, the reply will have a root element data containing all retrieved information wrapped in endpoint-specific objects, and if there was an error, the response will have an apiVersion element and error element, that will contain code, message and errors sub-elements. The errors sub-element may contain details about the exception that occured.

Should you receive a 500 class error (any error code starting with the number 5) indicating a server problem, we kindly ask you to contact us and provide the api call url you used when you received the error, and the response.

To display endpoint-specific information about the response, click the button under the 'response' subtitle.

Authentication

The REST API accepts HTTP Basic Authentication. A base64 encoded string containing your password and username is sent in the request headers with each api call over a secure https protocol.

Endpoints that require authorized access are marked with icon

If no credentials are provided, anonymous access is granted for all GET methods (Any data retrieval). Anonymous access may cause some of the endpoints to filter out results that require authorized access (E.g. experiments and platforms that are marked as unusable or private).

Username =
Your gemma username. If you need to create a new Gemma account, please go to the Gemma website and register (click 'Log in' in the upper right corner, to show the login window, then click the 'Need an account? Register' button).
Password =
Your gemma password. If you forgot your password, you can reset it through the Gemma website (click 'Log in' in the upper right corner, to show the login window, then click the 'Forgot your password' link).

If you provide credentials that are invalid, all calls will return a '401 - Unauthorized' error, even if they allow anonymous access.

Using this website, some browsers might prompt you for credentials again, if this form contains invalid ones.

Make sure to test your credentials before bulk queries, e.g. by calling the root endpoint.


Dataset endpoints

Endpoints accessing datasets (i.e. expression experiments), and their associated properties and files


Platform endpoints

Endpoints accessing platforms, and their associated properties and files


Gene endpoints

Endpoints accessing genes (non taxon-specific). Most endpoints also have a taxon-specific counterpart in the 'Taxon endpoints'.

Please be aware that the 'Official symbol' identifier of a gene refers to a set of gene homologues. Using the official symbol as a gene parameter for these endpoints will yield an arbitrary homologue (likely the same one every time, but that is not guaranteed). Use the methods from the 'Taxon endpoints' if you want to use the official symbol for a specific homologue.

Taxon endpoints

Endpoints accessing data for specific taxa. E.g: Taxon-specific genes or datasets

l

Other endpoints

Annotations, search, etc.