BV-BRC Data API

The BV-BRC Data API Service allows developers to query and retrieve both public and private (when authorized) data from the BV-BRC. The API is common to all data types within the system.

Data Types

The following data types are exposed from the BV-BRC. Click on a data type below to go to the data type's detail page for attribute information and specific examples.

Core API

The core BV-BRC Data API is a provided through a simple HTTP interface. The core set of functionality provides object retrieval by ID and querying for any of the above data types. All of this functionality can be accessed via common HTTP GET and POST requests.

There is also a NodeJS client, BVBRC JS Client, available for developer use. This client provides access to all of the common methods and may also provide some sugar functions for common queries. Most of the data is also available through this API via the BV-BRC Command Line Interface.

Data Retrieval by ID

For each of the defined data types, data can be retrieved directly by ID. The specific type of ID used is defined by the data type's primary key and can be seen by clicking on one of the above data types.

The endpoint for data object retrieval is in the following form:

https://www.bv-brc.org/api/{DATA TYPE}/{ID}

Data Querying

Queries can be submitted as GET requests (with the query in the URL) or as POST requests with the query contained in the request body. The latter is useful for large queries which would exceed the maximum length of URLs supported by browsers/servers.

The endpoint for data querying with an HTTP GET is in the following form:

https://www.bv-brc.org/api/{DATA TYPE}/?{QUERY}

The endpoint for data querying with an HTTP POST is nearly the same, but the query goes in the body instead of the URL:

https://www.bv-brc.org/api/{DATA TYPE}/

There are a couple of options allowed when using the HTTP POST method to submit a query. By specifying the HTTP CONTENT-TYPE Header, the API allows queries to be submitted as RQL or SOLR queries. To submit a RQL query, specify CONTENT-TYPE as:

application/x-www-form-url-encoded
or 
application/rqlquery+x-www-form-urlencoded

To submit a SOLR style query, use

application/solrquery+x-www-form-urlencoded

RQL Operators

The following operators are available for RQL Queries:

  • eq
    FIELD equals VALUE
    eq(FIELD,VALUE)
  • ne
    FIELD is not equal to VALUE
    ne(FIELD,VALUE)
  • gt
    FIELD is greater than VALUE
    gt(FIELD,VALUE)
  • lt
    FIELD is less than VALUE
    lt(FIELD,VALUE)
  • keyword
    Text search accross string values in a data type
    keyword(VALUE)
  • in
    True for objects whose FIELD contains any of the provided values
    in(FIELD,(VALUE1,VALUE2,VALUE3))
  • and
    ANDs two or more expressions together
    and(EXPRESSION,EXPRESSION,...)
  • or
    ORs two ore more expressions together
    or(EXPRESSION,EXPRESSION,...)
  • select
    Returns only the specified fields for query result objects
    select(FIELD1,FIELD2,FIELD3,....)
  • sort
    Sort results by field. Specify + or - to specify the sort direction
    sort([+|-]FIELD,[+|-]FIELD2)
  • limit
    Limits the results to COUNT records starting at START
    limit(COUNT,START)
  • GenomeGroup
    Retrieves the GenomeGroup from WORKSPACE_PATH for use in a query (e.g., &in(genome_id,GenomeGroup(/path/to/my/group)) )
    GenomeGroup(WORKSPACE_PATH)
  • FeatureGroup
    Retrieves the FeatureGroup from WORKSPACE_PATH for use in a query (e.g., &in(feature_id,FeatureGroup(/path/to/my/group)) )
    FeatureGroup(WORKSPACE_PATH)
  • facet
    Allows facets to be specified along with a query. Facet results are included in the HTTP response header when the response content-type is application/json and included in the response body for application/solr+json
    facet((FACET_PROPERTY,PROPERTY_VALUE),(FACET_PROPERTY,PROPERTY_VALUE),...)

Note that it is important to URL Encode FIELD names and VALUES individually (not entire query expressions): 

const query = `eq(${encodeURIComponent(field)},${encodeURIComponent(value)})`
vs 
const query = encodeURIComponent(`eq(${field},${value})`);

The former is correct, while the latter will encode the RQL operators themselves and cause failures.

Private Data

Private data is accessed using the same API as the rest of the system. To access private data, add an HTTP Authorization header to your request with your BV-BRC Access Token. No authorization token is currently required to access the PUBLIC data, though this may change in the future.

HTTP Headers

Both requests and responses to the API may contain useful information and directives in the HTTP headers. For requests, developers can do things like control the format of the data response. Response headers in queries for example contain information about the total size of the result set even though only a portion may be retrieved.

Important Request Headers

  • ACCEPT - Defines the format of the response. Commonly 
    application/json
    , but other formats are also available. Formats available for each data type are listed on the data type detail pages.
  • AUTHORIZATION - User Authorization Token, if any.
  • ACCEPT-RANGE - Range of items requested
  • CONTENT-TYPE - For POST requests, this defines the type of data in the body

Important Response Headers

  • CONTENT-TYPE - The format of the data being returned
  • CONTENT-RANGE - The range of the data being return; e.g. "items 0-9/99"

Sometimes it is inconvenient or impossible to set an HTTP Request header. This API allows HTTP headers to be set by appending a query string to the URL in the form of 

?http_HEADER=VALUE
. For example, 
?http_accept=application/json