BAM query API¶

Bam-server can return portions of BAM files using 3 different strategies:

Extracting a range of bytes (IGV.js uses that);
Using samtools (if available);
Using Picard-tools/htsjdk to return reads in JSON format.

Authorization¶

Only registered users (present in bam-server’s database in the users table) can use these routes.

Users are identified using an Authorization header to be added to the request, containing a signed Bearer token (JWT, see Authorization protocol). All requests expect such a header. For example:

curl -i -H "Authorization: Bearer xxxx.yyyy.zzzz" -X POST -d '{"sample": "SAMPLE1"} http://localhost:9000/bai
curl -i -H "Authorization: Bearer xxxx.yyyy.zzzz" http://localhost:9000/bai/SAMPLE1

Alternatively, all request can accept a URL argument ?token=<JWT> to pass the token. This mode is not recommended but sometimes necessary, depending on client library constraints. For example:

curl -i http://localhost:9000/bai/SAMPLE1?token=xxxx.yyyy.zzzz

API¶

Let :sample/<sample> be a sample identifier in the database;

Let <range> be a bytes range, formatted as “123-456”;

Let <region> be a genomic region, formatted as “chr1:10000-20000”. The chromosome names are those referenced in the BAM file header.

GET /

Says “BAM server operational.”, just to test if the server is listening.

BAM index¶

POST /bai                                   # data = '{"sample": "<sample>"}'
GET /bai/:sample

Returns the content of the index (.bai) for that BAM file.

Range query¶

POST /bam/range                             # data = '{"sample": "<sample>"}'
GET /bam/range/:sample

Returns the content of the BAM file, expecting an HTTP Range header to extract only the bytes range of interest - likely based on the BAM index. The bytes range can also be passed as an argument to the request (?range=<range>). Return the content as binary.

Using samtools¶

POST /bam/samtools?region=<region>          # data = '{"sample": "<sample>"}'
GET /bam/samtools/:sample?region=<region>

Uses samtools (if available) to extract the region (samtools view -hb <bam> <region>). Return the content as binary.

Reads in JSON format¶

POST /bam/json?region=<region>              # data = '{"sample": "<sample>"}'
GET /bam/json/:sample?region=<region>

Returns the reads for the given region in JSON format, using the htsjdk library. The fields correspond to the SAM file columns:

[
  {
     "name": "HISEQ:206:C8E95ANXX:3:2113:2451:6639",   // read name
     "flag": 99,
     "chrom": "chr1",       // reference name
     "start": 1234,         // leftmost mapping position
     "end": 1334,           // rightmost mapping position
     "mapq": 50,            // mapping quality
     "cigar": "101M",       // cigar string
     "rnext": "=",          //
     "pnext": 4567,         //
     "tlen": 283,           // template length, aka insert size
     "seq": "AATTAGGA...",  // [ACGTN=.],
     "qual": "AB<B@G>F..."  // per-base quality
  },
...
]