VDJdb server API

Accessing metadata

General information on database metadata (such as column IDs, names, etc..) can be obtained by performing a GET request to /api/database/meta.

HTTP Request

GET /api/database/meta

Example

$ curl -X GET https://vdjdb.cdr3.net/api/database/meta

The above command returns JSON structured like this:

{
    "metadata": {
        "numberOfRecords": Number,
        "numberOfColumns": Number,
        "columns":         Array[ColumnInfo]
    }
}

where ColumnInfo structured like this:

{
    "name":         String,       // Column's name
    "columnType":   String,       // 'txt' or 'seq'
    "visible":      Boolean,      // Should be always true
    "dataType":     String,       // Internal data type
    "title":        String,       // Formatted name
    "comment":      String,       // Column's description
    "values":       Array[String] // An array of all possible values (if available)
}

Accessing specific column info

HTTP Request

GET /api/database/meta/columns/:column

Note

You must replace :column with the correct column’s name.

Example

$ curl -X GET https://vdjdb.cdr3.net/api/database/meta/columns/gene

The above command returns the following JSON structure:

{
    "column": {
        "name":       "gene",
        "columnType": "txt",
        "visible":    true,
        "dataType":   "factor",
        "title":      "Gene",
        "comment":    "TCR chain: alpha or beta.",
        "values":     [ "TRA", "TRB" ]
    }
}

Querying the database

You can query the database by sending a POST request with a specific JSON content

HTTP Request

POST /api/database/search

Request parameters

Request JSON structure:

{
    "filters":   Array[Filter],
    "page":      Optional[Number],      // Optional: page, if not specified server will return all filtered rows from database
    "pageSize":  Optional[Number],      // Optional: page size, used only if ``page`` is specified. Default: 25
    "paired":    Optional[Boolean],     // Optional: specifies whether to include the paired records. Default: false
    "sort":      Optional[String],      // Optional: sort rule, it has the following structure: "<columnName>:<sortType>".
                                        //           Available sort types: 'asc' - asceding order, 'desc' - descending order
                                        //           Example: "gene:asc"
}

Filter structure:

{
    "column":     String,               // Column's name
    "filterType": FilterType,           // Filter type (list of all available types will be described below)
    "negative":   Boolean,              // Invert the filter: return only results that do **NOT** match the filter
    "value":      String                // Filter's value
}

FilterType available options:

"exact"         // Exact match
"exact:set"     // Comma separated values, exact match for at least one value.
"substring:set" // Comma separated values, substring match for at least one value.
"pattern"       // Pattern match
"level"         // Number, greater or equal than **value**
"range"         // Range for numbers, it has the following structure "<min>:<max>". Example: "5:10"
"sequence"      // Fuzzy match filter, it has the following structure "<query>:<substitutions>:<insertions>:<deletions>"
                // Note that sequence filter can be only applied to column with 'seq' columnType.
                // Example: "CASSFGVNSDYTF:1:1:1"

Example 1

Fetching information about CAAAASGGSYIPTF.

$ curl https://vdjdb.cdr3.net/api/database/search    \
   -H "Content-Type: application/json"               \
   -X POST                                           \
   -d '{ "filters" : [{ "column" : "cdr3", "value" : "CAAAASGGSYIPTF", "filterType" : "exact", "negative" : false }] }'

The above command will response in:

{
    "page":        -1,
    "pageSize":    -1,
    "pageCount":    1,
    "recordsFound": 1,
    "rows":         [{
        "entries":  [ "TRA", "CAAAASGGSYIPTF", "TRAV1-2*01", "TRAJ6*01", "HomoSapiens", ...etc ],
        "metadata": {
            "pairedID":    "3236",
            "cdr3vEnd":         2,
            "cdr3jStart":       4
        }
    }]
}

The above response has the following JSON structure:

{
    "page":         Number,          // Current page, equals -1 if 'page' argument was not specified in request
    "pageSize":     Number,          // Page size, equals -1 if 'page' argument was not specified in request
    "pageCount":    Number,          // Pages count, equals -1 if 'page' argument was not specified in request
    "recordsFound": Number,          // Filtered records count (it is not include paired rows)
    "rows":         Array[SearchRow] // Filtered database entries
}

SearchRow has the following structure:

{
    "entries":      Array[String],   // Array of entries, the order of the elements matches the order of columns
                                     // See `Accessing metadata` section.
    "metadata":     {
        "pairedID":     String,      // Specifies paired record stringified ID number. If record isn't paired the value will be equal to "0".
        "cdr3vEnd":     Number,      // V region end index in cdr3 sequence.
        "cdr3jStart":   Number       // J region start index in cdr3 sequence.
    }
}

Example 2

Fetching information about CAAAASGGSYIPTF and his paired record.

$ curl https://vdjdb.cdr3.net/api/database/search    \
   -H "Content-Type: application/json"               \
   -X POST                                           \
   -d '{ "filters" : [{ "column" : "cdr3", "value" : "CAAAASGGSYIPTF", "filterType" : "exact", "negative" : false }], "paired": true }'

The above command will response in:

{
    "page":         -1,
    "pageSize":     -1,
    "pageCount":    -1,
    "recordsFound":  1,
    "rows":         [
        { "entries": [ "TRA", "CAAAASGGSYIPTF", ...etc ], "metadata": { "pairedID": "3236", "cdr3vEnd": 2, "cdr3jStart": 4 } },
        { "entries": [ "TRB", "CASGTGDSNQPQHF", ...etc ], "metadata": { "pairedID": "3236", "cdr3vEnd": 4, "cdr3jStart": 7 } }
    ]
}