API

FireProtDB provides programmatic access via a REST API. This page will help you understand how to use the API.

Quick links

Swagger UI (tab) – a user-friendly client and documentation of the API, useful to try out the API and learn about it.
fireprotdb-openapi.json – the API definition based on the OpenAPI 3.0 specification.
search-query-schemas.zip – the JSON schemas of the search query.

1. Experiment search

The FireProtDB search service has two types of entries: a sequence-experiment entry and a mutant-experiment entry. An entry represents a sequence or a mutant, combined with an experiment. Sequence experiments have absolute measurements obtained from a single sequence, most commonly a wild-type sequence. A mutant represents a pair of sequences (source and target) and so mutant experiments have both absolute measurements (for target) and relative measurements (comparing source and target).

URL parameters

The search endpoint /api/search has several URL parameters:

query – a serialized JSON object with a fulltext search phrase or an expression tree employing “search variables”.
offset – the index of the first returned entry, used for pagination.
limit – the maximum number of returned entries, used for pagination. The default is unlimited. For the json format, the default is 10 and the maximum limit is 500.
sort – a sorting criterion in a string format [VARIABLE],[ORDER], where [VARIABLE] is a “search variable” and [ORDER] is asc or desc. Multiple sorting criteria are supported using the form-explode serialization, e.g. sort=MUTATED_POSITION,asc&sort=DDG,desc.
format – json (the default), jsonl (one JSON object per row), csv, or tsv.
inline – browsers will try to display the result for true and they will open a download dialog for false. The default value for the json format is true, otherwise it is false.

Search query

The search query object has two fields: fulltext and tree. Exactly one of them must be used in a single request.

The fulltext search is straightforward: use your search phrase as a value for the fulltext field, and URL-encode the whole JSON object. The resulting URL should not contain special characters. For example, for the haloalkane dehalogenase search phrase, the query object is {"fulltext":"haloalkane dehalogenase"} and the resulting URL is the following:

/api/search?query=%7B%22fulltext%22%3A%22haloalkane%20dehalogenase%22%7D

The expression tree search is more complex yet more powerful. We define “search variables” organized into 5 groups: array-string, array-number, string, number, and boolean. Each group has a set of binary operators which can be used to construct elementary expressions. You can construct a complex query by building a tree, where leaf nodes representing elementary expressions are connected by inner nodes (AND, OR, NOT). All node types are precisely defined using JSON schemas: search-query-schemas.zip. The next diagram shows the type inheritance of different node types (this is not an actual query tree).

Figure 1: Inheritance diagram of different node types in the search query tree. Variable names used in the figure are abbreviated to save space.

For example, to search for experiments with a mutated residue position between 20 and 30, and with the target amino acid being M or G, the search query object is:

Figure 2: Query tree for the example expression.

The query tree has the following JSON representation:

Indent

{"tree":{"operator":"AND","children":[{"operator":"AND","children":[{"variable":"MUTATED_POSITION","operator":"GREATER_THAN_OR_EQUAL_TO","value":20},{"variable":"MUTATED_POSITION","operator":"LESS_THAN_OR_EQUAL_TO","value":30}]},{"operator":"OR","children":[{"variable":"TARGET_AMINO_ACID","operator":"EQUAL_TO","value":"M"},{"variable":"TARGET_AMINO_ACID","operator":"EQUAL_TO","value":"G"}]}]}}

The corresponding URL is:

/api/search?query=%7B%22tree%22%3A%7B%22operator%22%3A%22AND%22%2C%22children%22%3A%5B%7B%22operator%22%3A%22AND%22%2C%22children%22%3A%5B%7B%22variable%22%3A%22MUTATED_POSITION%22%2C%22operator%22%3A%22GREATER_THAN_OR_EQUAL_TO%22%2C%22value%22%3A20%7D%2C%7B%22variable%22%3A%22MUTATED_POSITION%22%2C%22operator%22%3A%22LESS_THAN_OR_EQUAL_TO%22%2C%22value%22%3A30%7D%5D%7D%2C%7B%22operator%22%3A%22OR%22%2C%22children%22%3A%5B%7B%22variable%22%3A%22TARGET_AMINO_ACID%22%2C%22operator%22%3A%22EQUAL_TO%22%2C%22value%22%3A%22M%22%7D%2C%7B%22variable%22%3A%22TARGET_AMINO_ACID%22%2C%22operator%22%3A%22EQUAL_TO%22%2C%22value%22%3A%22G%22%7D%5D%7D%5D%7D%7D

Tip: Try out the debug mode in the “advanced search” form on the website and see how search query trees are constructed.

Response format

The result content format depends on the format URL parameter.

json – the whole response body is a single JSON array containing JSON objects of the SearchEntry type. Easy to process, but needs pagination. Maximum page size (the limit URL parameter) is 500 entries.
jsonl – the json-lines format provides JSON objects of the SearchEntry type on separate lines. This format is useful for stream processing. It has no maximum limit because the API sends entries in a streaming manner.
csv – a comma-separated tabular format. The columns are designed to be similar to the columns of a results table on the website. This format can be easily imported to spreadsheets such as Microsoft Excel. It has no maximum limit.
tsv – a tab-separated tabular format. Alternative to the csv format.

The SearchEntry type has two fields: sequence and mutant. Each entry has only one of these fields, that is, the entry represents either a sequence-experiment pair or a mutant-experiment pair. You will find all type definitions in the API definition file: fireprotdb-openapi.json.

2. Sequence

The sequence page lists all experiments for a particular sequence and provides additional sequence features. Data can be obtained using these endpoints:

/api/sequences/{id} – a JSON object of the SequenceDetailEntry type with the specified sequence ID.
/api/sequences/{id}/sequence – the amino acids of the sequence with the specified sequence ID as a JSON string (quoted).

Mutants are not part of SequenceDetailEntry. To obtain all mutants for the sequence, use the search endpoint with the following query:

{
  "tree": {
    "operator": "AND",
    "children": [
      {
        "variable": "SOURCE_SEQUENCE_ID",
        "operator": "EQUAL_TO",
        "value": "{id}"
      },
      {
        "variable": "MUTATED_POSITION",
        "operator": "IS_EMPTY",
        "value": false
      }
    ]
  }
}

3. Mutant

The mutant page lists all experiments for a particular mutant. Data can be obtained using this endpoint:

/api/mutants/{id} – a JSON object of the MutantDetailEntry type with the specified mutant ID.