REST API

This document describes the implementation of the REST-based MolMeDB public interface (API), which allows one to access MolMeDB database data easily. In most cases there are three steps to correctly access the MolMeDB data:

1. Find the required endpoint (category) and set the URL to access it (see List of endpoints below).
2. Set parameters specifying a request.
3. (Optional) Set Accept request header parameter to inform the server about the required output data format.

If you have comments, advice, or suggestions to improve the functionality (e.g. new endpoint definition), please contact us at molmedb@upol.cz.

URL endpoints structure

Each endpoint (EP) is determined by a unique URL address composed of four main parts. API resources have common HTTP URL composition:

• URI - Common for all requests - https://molmedb.upol.cz/api.
• Category - All endpoints are categorized according to the nature of the data they return (e.g. membrane, method, compound, ...).
• EP specification - Specific and unambiguous determination of the called endpoint.
• Parameters - A more detailed description of the parameters will be part of each endpoint separately.

Figure 1. Structure of the URL address for each MolMeDB API request.

Most parameters can be fitted directly as part of the URL divided by the `/` character. But parameters including special characters, such as `/`, `#`, etc., must be adequately encoded not to violate URL syntax. These encoded parameters are usually inserted into the URL as GET_parameters (see above) divided by the `&` character (see basic URL syntax for more info).

Access rules

MolMeDB database data are freely accessible, and there is no limitation on API usage. All functions specified in this document should be accessed using GET method (unless otherwise stated) and are freely accessible. Several methods also support POST request method allowing parameters to be set in a request body instead of being part of the URL. The reason is that the URL address has a length limit set to 2048 characters and thus is unsuitable for long queries.

Important

Private methods are accessible only after successful query authorization; therefore, if called request returns 401 - Unauthorized response, check the correctness of your request.

Output data format

The requested output data format should be specified in the header of the user request in the parameter Accept with valid MIME as value (see table below). Data are returned in the default endpoint format if no value is specified. The application currently supports JSON format for almost all API requests, and this format is also recommended because of its flexibility and machine readability. RDF data is typically returned in XML/RDF format. Tabular data can also be formatted as CSV or XLSX file format for subsequent processing in a standard spreadsheet editor, such as MS EXCEL.

Supported MIMEs

Following MIMEs can be set in Accept header parameter to obtain query result in requested format:

Example

# HTTP request header
...
Accept: application/json
...

# HTTP request header
...
Accept: application/json
...

TIP 

One can put multiple Accept options separated by comma character to specify more possible acceptable formats with priority set by their order. Server then returns data in the first possible output format matching in Accept parameter.

Example

Accept: text/html, application/json, text/plain

Given accept parameter specifies, that data should be returned in HTML, JSON or PLAIN TEXT formats (in this order).

Warning

If a client does not set Accept parameter value, the server returns data in the default format specified in the endpoint definition.

Response status codes

The status code indicates whether the requested operation was successful. The correctly evaluated HTTP request has status code 200 (OK) or 204 (No content) and if some error occurs during evaluation, a specific code with text describing the type of error is returned: