This section describes the different classes related to workflows, workfunctions and WorkChains.

Implementation of RESTful API for based on flask + flask_restful module For the time being the API returns the parsed valid endpoints upon GET request Author: Snehal P. Waychal and Fernando Gargiulo @ Theos, EPFL

class aiida.restapi.api.AiidaApi(app=None, **kwargs)[source]

AiiDA customized version of the flask_restful Api class


this method handles the 404 “URL not found” exception and return custom message :param e: raised exception :return: list of available endpoints

class aiida.restapi.api.App(*args, **kwargs)[source]

Basic Flask App customized for this REST Api purposes

Resources for REST API

class aiida.restapi.resources.BaseResource(**kwargs)[source]

Each derived class will instantiate a different type of translator. This is the only difference in the classes.

get(id=None, page=None)[source]

Get method for the Computer resource :return:

class aiida.restapi.resources.Node(**kwargs)[source]

Differs from BaseResource in trans.set_query() mostly because it takes query_type as an input and the presence of additional result types like “tree”

get(id=None, page=None)[source]

Get method for the Node resource. :return:

aiida.restapi.run_api.run_api(App, Api, *args, **kwargs)[source]

Takes a flask.Flask instance and runs it. Parses command-line flags to configure the app.


Class inheriting from Flask app class


flask_restful API class to be used to wrap the app


required by argparse


List of valid parameters

  • prog_name:name of the command before arguments are parsed. Useful when api is embedded in a command, such as verdi restapi
  • default_host: self-explanatory
  • default_port: self-explanatory
  • default_config_dir = directory containing the file used to
  • configure the RESTapi
  • parse_aiida_profile= if True, parses an option to specify the AiiDA

All other passed parameters are ignored.

This file contains the exceptions that are raised by the RESTapi at the highest level, namely that of the interaction with the client. Their specificity resides into the fact that they return a message that is embedded into the HTTP response.

Example: .../api/v1/nodes/ ... (TODO compete this with an actual example)

Other errors arising at deeper level, e.g. those raised by the QueryBuilder or internal errors, are not embedded into the HTTP response.

exception aiida.restapi.common.exceptions.RestInputValidationError[source]

document with an example

exception aiida.restapi.common.exceptions.RestValidationError[source]

document with an example

class aiida.restapi.common.utils.CustomJSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None)[source]

Custom json encoder for serialization. This has to be provided to the Flask app in order to replace the default encoder.

class aiida.restapi.common.utils.Utils(**kwargs)[source]

A class that gathers all the utility functions for parsing URI, validating request, pass it to the translator, and building HTTP response

An istance of Utils has to be included in the api class so that the configuration parameters used to build the api are automatically accessible by the methods of Utils without the need to import them from the file.


This function constructs a filter for a datetime object to be in a certain datetime interval according to the precision.

The interval is [reference_datetime, reference_datetime + Dt], where Dt is a function fo the required precision.

This function should be used to replace a datetime filter based on the equality operator that is inehrently “picky” because it implies matching two datetime objects down to the microsecond or something, by a “tolerant” operator which checks whether the datetime is in an interval.

Returns:a suitable entry of the filter dictionary
build_headers(rel_pages=None, url=None, total_count=None)[source]

Construct the header dictionary for an HTTP response. It includes related pages, total count of results (before pagination). :param rel_pages: a dictionary defining related pages (first, prev, next, last) :param url: (string) the full url, i.e. the url that the client uses to get Rest resources :return:

build_response(status=200, headers=None, data=None)[source]
  • status – status of the response, e.g. 200=OK, 400=bad request
  • headers – dictionary for additional header k,v pairs, e.g. X-total-count=<number of rows resulting from query>
  • data – a dictionary with the data returned by the Resource

a Flask response object


Takes a list of elements resulting from the parsing the query_string and elaborates them in order to provide translator-compliant instructions

Parameters:field_list – a (nested) list of elements resulting from parsing the query_string
Returns:the filters in the
paginate(page, perpage, total_count)[source]

Calculates limit and offset for the reults of a query, given the page and the number of restuls per page. Moreover, calculates the last available page and raises an exception if the required page exceeds that limit. If number of rows==0, only page 1 exists :param page: integer number of the page that has to be viewed :param perpage: integer defining how many results a page contains :param total_count: the total number of rows retrieved by the query :return: integers: limit, offset, rel_pages

parse_path(path_string, parse_pk_uuid=None)[source]

Takes the path and parse it checking its validity. Does not parse “io”, “content” fields. I do not check the validity of the path, since I assume that this is done by the Flask routing methods.

  • path_string – the path string
  • parse_id_uuid – if ‘pk’ (‘uuid’) expects an integer (or a string with the first characters of the uuid, as long as they uniquely define a UUID)

a tuple (source_type, page, id, query_type) where:

  • source_type (string)
  • page (integer)
  • id (string: uuid starting pattern, int: pk)
  • query_type (string))


Function that parse the querystring, extracting infos for limit, offset, ordering, filters, attribute and extra projections. :param query_string (as obtained from request.query_string) :return: parsed values for the querykeys

Parameters:path – entire path contained in flask request
Returns:list of each element separated by ‘/’

Removes the PREFIX from an URL path. PREFIX must be defined in the file. For example, PREFIX = “/api/v2”, path = “/api/v2/calculations/page/2” strip_prefix(path) ==> “/calculations/page/2”

Parameters:path – the URL path string
Returns:the same URL without the prefix
validate_request(limit=None, offset=None, perpage=None, page=None, query_type=None, is_querystring_defined=False)[source]

Performs various checks on the consistency of the request. Add here all the checks that you want to do, except validity of the page number that is done in paginate(). Future additional checks must be added here

class aiida.restapi.common.utils.datetime_precision(dt, precision)[source]

A simple class which stores a datetime object with its precision. No internal check is done (cause itis not possible).

precision: 1 (only full date)
2 (date plus hour) 3 (date + hour + minute) 4 (dare + hour + minute +second)

List available routes