# bedhost

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Github badge](https://img.shields.io/badge/source-github-354a75?logo=github)](https://github.com/databio/bedhost)


`bedhost` is a Python FastAPI module for the API that powers BEDbase.
It needs a path to the *bedbase configuration file*, which can be provided either via `-c`/`--config` argument or read from `$BEDBASE_CONFIG` environment variable. 

## Introduction

You can find the formal OpenAPI documentation and interactive interface at <https://api.bedbase.org/v1/docs>. This document provides more conceptual introduction and explanations to how to use the API effectively.


## General API organization

### Data types

BEDbase stores two types of data, which we call *records*. They are 1. BEDs, and 2. BEDsets. BEDsets are simply collections of BEDs. Each record in the database is either a BED or a BEDset.

### Endpoint organization

The endpoints are divided into 3 groups:

1. `/bed` endpoints are used to interact with metadata for BED records.
2. `/bedset` endpoints are used to interact with metadata for BEDset records.
3. `/objects` endpoints are used to download metadata and get URLs to retrieve the underlying data itself. These endpoints implement the [GA4GH DRS standard](https://ga4gh.github.io/data-repository-service-schemas/).

Therefore, to get information and statistics about BED or BEDset records, or what is contained in the database, look through the `/bed` and `/bedset` endpoints. But if you need to write a tool that gets the actual underlying files, then you'll need to use the `/objects` endpoints. The type of identifiers used in each case differ.

## Record identifiers vs. object identifiers

Each record has an identifier. For example, `0000120fe8c5334bb0ce759dfcf06c3b` is a BED identifier. You can use this identifier for the metadata endpoints. To download files, you'll need something slightly different -- you need an *object identifier*. This is because each BED record includes multiple files, such as the original BED file, the BigBed file, analysis plots, and so on. To download a file, you will construct what we call the `object_id`, which identifies the specific file.

### How to construct object identifiers

Object IDs take the form `<record_type>.<record_identifier>.<result_id>`. An example of an object_id for a BED file is `bed.0000120fe8c5334bb0ce759dfcf06c3b.bed_file`

So, you can get information about this object like this:

`GET` [https://api.bedbase.org/v1/objects/bed.0000120fe8c5334bb0ce759dfcf06c3b.bed_file](https://api.bedbase.org/v1/objects/bed.0000120fe8c5334bb0ce759dfcf06c3b.bed_file)

Or, you can get a URL to download the actual file with:

`GET` [https://api.bedbase.org/v1/objects/bed.0000120fe8c5334bb0ce759dfcf06c3b.bed_file/access/http](https://api.bedbase.org/v1/objects/bed.0000120fe8c5334bb0ce759dfcf06c3b.bed_file/access/http)