# API Reference

## Important update

The APIs described below are out-of-date and will not be supported soon. For the up-to-date APIs, please refer to the our preprint at BioRxiv (Supplementary Table 4):

FinaleDB: a browser and database of cell-free DNA fragmentation patterns Haizi Zheng, Michelle S Zhu, Yaping Liu bioRxiv 2020.08.18.255885; doi: <https://doi.org/10.1101/2020.08.18.255885>

## Authentication

Currently, FinaleDB doesn't require authentication to use its API.

## FinaleDB summary

<mark style="color:blue;">`GET`</mark> `http://finaledb.research.cchmc.org/api/v1/summary`

This endpoint returns you a summary report about FinaleDB.

{% tabs %}
{% tab title="200 Describe the number of entries grouped by different aspects." %}

```
{
    "http://localhost:5000/samples?frag_num=38084192,38084196": 2579,
    "sampleCnt": 2505,
    "instrument": {
        "NextSeq 500": 141,
        "HiSeq 4000": 5,
        "NovaSeq 6000": 3
    },
    "disease": {
        "Colorectal cancer": 48,
        "Liver cancer": 93,
        "Ovarian cancer": 30,
        "Hepatitis B": 67
    },
    "tissue": {
        "urine": 139
    },
    "assay": {
        "WGS": 2572,
        "WXS": 7
    }
}
```

{% endtab %}
{% endtabs %}

## Make queries

<mark style="color:blue;">`GET`</mark> `http://finaledb.research.cchmc.org/api/v1/seqrun`

Returns a list of records matching filters and queries terms specified by this API.\
\
Example: the following request will blindly return the first 5 records in the dataset:\
\
<http://finaledb.research.cchmc.org/api/v1/seqrun?limit=5>

#### Query Parameters

| Name       | Type    | Description                                                                                                                             |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| offset     | integer | Specify the offset of the returned items                                                                                                |
| limit      | integer | Return entries associated with certain samples.                                                                                         |
| disease    | string  | Return entries associated with the specified pathological condition                                                                     |
| tissue     | string  | Return entries associated with the specified tissue.                                                                                    |
| ID         | string  | Database entry ID                                                                                                                       |
| frag\_num  | string  | Format: min\_value,max\_value. For example: frag\_num=38713820,38713890. Return entries with the number of fragments between the range. |
| instrument | boolean | Return entries sequenced by the specified sequencing instrument.                                                                        |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{    "name": "Cake's name",    "recipe": "Cake's recipe name",    "cake": "Binary cake"}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{    "message": "Ain't no cake like that."}
```

{% endtab %}
{% endtabs %}