Example calls PLAZA API

The PLAZA API is a RESTful API that can be used independently from the query programming language.

However, implementation differences might exist due to different programming paradigms. Therefore we present some code examples here about how to use the PLAZA API.

More information about the PLAZA API can be found here.

/*
 * Example JavaScript code for the PLAZA API
 */

// Set which PLAZA instance's API to use
var plaza_instance = "https://bioinformatics.psb.ugent.be/plaza/versions/plaza_v4_monocots/api/v2";

var token_requests_path = plaza_instance + "/token_requests/";
var species_path = plaza_instance + "/species/";

function getSpecies(api_token, args) {
	jQuery.ajax({
		url: species_path,
		type: "GET",
		beforeSend: function(xhr) {
			xhr.setRequestHeader("Authorization", "Bearer " + api_token);
		},
		data: args,
		success: function(response) {
			console.log(response);
		},
		error: function(xhr, status, error) {
			console.error(error);
		},
		// Synchronously for demonstration purposes. Use async or js promises in real code
		async: false
	});
}

// Authenticate, optionally with your workbench credentials. Here we've
// omitted the credentials, which gives us guest access. Guests are
// throttled more strictly than workbench users, so it's preferable
// to provide credentials.
console.log('Post token request');
jQuery.post(
	token_requests_path,
	{},
	function(response) {
		// Each response is logged to the browser's console, in this
		// example (Ctrl-Shift-J in FireFox, F12 in Chrome)

		// Get response
		try {
			// data is a JSON object containing the response
			console.log(response);
			var api_token = response.result.token;
		}
		catch (err) {
			console.error(err);
			return;
		}
		
		// Get all species, without genes
		console.log('Get all species');
		getSpecies(api_token, {})

		// Get nothing. Note how ids=[] is not the same as omitting ids as we did
		// above. Think of ids as 'filter by these ids', when given no ids=[],
		// nothing remains. When omitting the ids argument entirely, no filtering of
		// ids is requested and thus all is returned. (If ids=[] had returned all
		// species, this would be surprising when passing on a list of ids to filter
		// by which happens to be empty, and getting all species in return instead
		// of the expected, none.)
		console.log('Get none of the species');
		getSpecies(api_token, {ids: ''})

		// Get ath with genes
		console.log('Get ath with genes');
		getSpecies(api_token, {ids: 'ath', include: 'genes'})

		// Get ath and col without genes. Note that multiple values are
		// specified as a comma separated string
		console.log('Get ath and hvu without genes');
		getSpecies(api_token, {ids: 'ath,hvu'})
	}
);
from plaza_api.rest import ApiException
from pprint import pprint
import plaza_api
import logging
import sys

_logger = logging.getLogger(__name__)

# Set which PLAZA instance's API to use
plaza_api.configuration.host = 'https://bioinformatics.psb.ugent.be/plaza/versions/plaza_v4_monocots/api/v2'

try:
    # Authenticate, optionally with your workbench credentials. Here we've
    # omitted the credentials, which gives us guest access. Guests are
    # throttled more strictly than workbench users, so it's preferable
    # to provide credentials.
    authentication = plaza_api.AuthenticationApi()
    response = authentication.token_requests_post()
    pprint(response)

    # Configure all PLAZA API with the JWT token we got back, prefixing it with
    # 'Bearer '
    plaza_api.configuration.api_key['Authorization'] = response.result.token
    plaza_api.configuration.api_key_prefix['Authorization'] = 'Bearer'

    # Get all species, without genes
    species_api = plaza_api.SpeciesApi()
    response = species_api.species_get()
    pprint(response)

    # Get nothing. Note how ids=[] is not the same as omitting ids as we did
    # above. Think of ids as 'filter by these ids', when given no ids=[],
    # nothing remains. When omitting the ids argument entirely, no filtering of
    # ids is requested and thus all is returned. (If ids=[] had returned all
    # species, this would be surprising when passing on a list of ids to filter
    # by which happens to be empty, and getting all species in return instead
    # of the expected, none.)
    response = species_api.species_get(ids=[])
    pprint(response)

    # Get ath with genes
    response = species_api.species_get(ids=['ath'], include=['genes'])
    pprint(response)
except ApiException as e:
    # ApiException is raised whenever an API call returns anything other than
    # HTTP response code 200 OK
    _logger.exception('Exception when calling an api')
    sys.exit(1)

To run the example, first install the PLAZA API Python client, and finally run it with:

python3 example.py