Fetching contributors…
Cannot retrieve contributors at this time
76 lines (58 sloc) 3.22 KB

BioThings API Specifications

BioThings APIs are APIs designed for biological entities. Here are the guidelines to follow when building a new BioThings API:

1. Endpoints

     BioThings API supports the following endpoints:

  • Query Service --- make query about a specific field, and return a list of matching entities
  • Entity Retrieval Service --- retrieve annotation based on an ID, e.g. HGVS ID>A
  • Metadata Retrieval Service --- retrieve metadata about the data available

2. Versioning

  • Include the version number (as "v1", "v2", "v3", and so on) to the endpoint URLs (e.g. endpoint)
  • Increase version number when breaking changes are introduced to the API

3. Supported HTTP Methods

     BioThings API endpoints support both ‘GET’ and ‘POST’ HTTP methods:

  • GET: perform a single entity-retrieval or a single query
  • POST: perform a batch of entity-retrieval or queries

4. Supported data formats

  • JSON
  • Msgpack (a binary JSON format, optional)

5. CORS support

     Biothings API endpoints support CORS with unrestricted hostnames, so that users can make cross-origin API requests directly from their web application.

6. JSONP support

     Biothings API endpoints support JSONP (also see here) with a query parameter “callback”, so that users can make JSONP API requests directly from their web applications.

7. HTTPS support

     BioThings API endpoints support both HTTP and HTPPS protocol, so that users can make encrypted API request if needed.

8. HTTP compression support

     BioThings API endpoints support gzip HTTP compression protocol to reduce the data transfer size.

9. HTTP caching support

     BioThings API endpoints support HTTP caching headers with both “Cache-Control” and “etag” headers (max-age is set to 7 days).

10. Common Parameters

  • Common parameter(s) supported by both query and entity retrieval services

    • fields

      • Use comma-separated fields to limit the fields returned from the variant object.
      • Use dot notation to return a field in a nested structure, e.g.“cadd.gene”.
      • Default: “fields=all”. If “fields=all”, all available fields will be returned.
    • callback

      • Optional
      • pass a “callback” parameter to make a JSONP call.>A?fields=clinvar.rcv.conditions, dbsnp
  • Common parameters supported only by query service

    • size

      • The maximum number of matching object hits to return
      • Optional, default is 10
    • from

      • The number of matching hits to skip
      • Optional, default is 0