smartapi.yaml

openapi: 3.0.3
info:
  contact:
    email: help@biothings.io
    name: BioThings Team
    x-id: https://github.com/biothings
    x-role: responsible developers
  description: >-
    Documentation of the BioThings API for 
    [BindingDB](https://www.bindingdb.org/rwd/bind/index.jsp) data.
  termsOfService: https://biothings.io/about
  title: BioThings BindingDB API
  version: '2022-06-01'
  x-translator:
    infores: "infores:biothings-bindingdb"
    component: KP
    team:
      - Service Provider
    biolink-version: "3.5.0"
servers:
- description: Encrypted Production server
  url: https://biothings.ncats.io/bindingdb
  x-maturity: production
- description: Production server
  url: http://biothings.ncats.io/bindingdb
  x-maturity: production
tags:
- name: association
- name: protein
- name: chemical
- name: query
- name: translator
- name: biothings
paths:
  "/association/{id}":
    get:
      description: >-
        By default, this will return the complete association in JSON format. If the input is not valid,
        404 (NOT FOUND) will be returned.
        

        Optionally, you can pass a "fields" parameter to return only the annotation you want 
        (by filtering returned object fields). "fields" accepts any attributes (a.k.a fields) available 
        from the association. Multiple attributes should be separated by commas. If an attribute is not 
        available for a specific association, it will be ignored. Note that the attribute names are 
        case-sensitive.


        Just like the query service, you can also pass a "callback" parameter to make a JSONP call.
      parameters:
      - name: id
        in: path
        required: true
        example: "456856-P35414"
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/callback"
      - "$ref": "#/components/parameters/email"
      ## this is useful even when it's not noted in the docs
      - "$ref": "#/components/parameters/size"
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/dotfield"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      ## commenting out schemas and other status codes for now
      #     content:
      #       application/json:
      #         schema:
      #           $ref: '#/components/schemas/Association'
      #   '404':
      #     description: A response indicating an unknown association ID
      tags:
      - association
  "/association":
    post:
      description: >-
        Although making simple GET requests above to our service is sufficient in most use cases, 
        there are some times you might find it easier to batch query (e.g., retrieving multiple associations). 
        Fortunately, you can also make batch queries via POST requests when you need to.
      parameters:
      - name: ids
        description: >-
          Accepts multiple association ids separated by commas. Note that currently we only take ids up to 
          1000 maximum, the rest will be omitted.


          The request body can also be used to provide these ids.
        in: query
        ## setting to false since putting this info in the request body seems to work as well
        required: false
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/email"
      ## this is useful even when it's not noted in the docs
      - "$ref": "#/components/parameters/size"
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/dotfield"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      requestBody:
        content:
          application/json:
            example:
              ids:
              - "456856-P35414"
              - "450507-Q13822"
            schema:
              type: object
              properties:
                ids:
                  description: >-
                    Accepts multiple association ids. Note that currently we only take the input ids 
                    up to 1000 maximum, the rest will be omitted.
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      tags:
      - association
  "/metadata":
    get:
      description: Get metadata about the data available from the API
      ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
      # parameters:
      # - "$ref": "#/components/parameters/format"
      # - "$ref": "#/components/parameters/raw"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      tags:
      - metadata
  "/metadata/fields":
    get:
      description: Get metadata about the data fields available from the API
      ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
      # parameters:
      # - "$ref": "#/components/parameters/format"
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/search"
      # - "$ref": "#/components/parameters/prefix"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      tags:
      - metadata
  "/query":
    get:
      description: >-
        Query service. In the output, "total" in the output gives the total number 
        of matching hits, while the actual hits are returned under "hits" field.
      parameters:
      - name: q
        description: >-
          Required, passing user query. The detailed query syntax for parameter is explained 
          [here for a core BioThings 
          API](https://docs.mychem.info/en/latest/doc/chem_query_service.html#query-syntax).
        in: query
        required: true
        example: "object.pubchem_cid:134329991"
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/size"
      - "$ref": "#/components/parameters/from"
      - "$ref": "#/components/parameters/fetch_all"
      - "$ref": "#/components/parameters/scroll_id"
      - "$ref": "#/components/parameters/sort"
      - "$ref": "#/components/parameters/facets"
      - "$ref": "#/components/parameters/facet_size"
      - "$ref": "#/components/parameters/callback"
      - "$ref": "#/components/parameters/dotfield"
      - "$ref": "#/components/parameters/email"
      ## these are noted in the /spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/aggs"
      # - "$ref": "#/components/parameters/userquery"
      # - "$ref": "#/components/parameters/explain"
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      ## commenting out schemas and other status codes for now
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/QueryResult"
      #   '400':
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/ErrorResult"
      #     description: A response indicating an improperly formatted query
      # summary: Make queries and return matching gene hits. Supports JSONP and CORS
      #   as well.
      tags:
      - query
    post:
      description: >-
        Although making simple GET requests above to our query service is sufficient for most use cases, 
        there are times you might find it more efficient to make batch queries (e.g., retrieving data 
        for multiple inputs). Fortunately, you can also make batch queries via POST requests when you need to.


        The "query” field in the returned object indicates the matching query term. If a query term has no match, 
        it will return with a “notfound” field with the value “true”.
      parameters:
      - name: q
        description: >-
          Accepts multiple values separated by commas. Note that currently we only take the input values up to 1000 
          maximum, the rest will be omitted.


          The request body can also be used to provide these ids.
        in: query
        ## setting to false since putting this info in the request body seems to work as well
        required: false
        schema:
          type: array
          items:
            type: string
      - name: scopes
        description: >-
          Optional, specify one or more fields (separated by commas) to search. Default: _id


          The request body can also be used to provide this information.
        in: query
        ## setting to false since putting this info in the request body seems to work as well
        required: false
        schema:
          type: string
      - "$ref": "#/components/parameters/fields"
      - "$ref": "#/components/parameters/email"
      ## this is useful even when it's not noted in the docs
      - "$ref": "#/components/parameters/size"
      - "$ref": "#/components/parameters/from"
      - "$ref": "#/components/parameters/fetch_all"
      - "$ref": "#/components/parameters/scroll_id"
      ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
      # - "$ref": "#/components/parameters/sort"
      # - "$ref": "#/components/parameters/raw"
      # - "$ref": "#/components/parameters/rawquery"
      # - "$ref": "#/components/parameters/dotfield"
      # - "$ref": "#/components/parameters/_sorted"
      # - "$ref": "#/components/parameters/always_list"
      # - "$ref": "#/components/parameters/allow_null"
      # - "$ref": "#/components/parameters/format"
      requestBody:
        content:
          application/json:
            example:
              q:
              - "134329991"
              - "134330137"
              scopes:
              - "object.pubchem_cid"
            schema:
              type: object
              properties:
                q:
                  description: >-
                    Accepts multiple values separated by commas. Note that currently we only take the input values 
                    up to 1000 maximum, the rest will be omitted.
                  type: array
                  items:
                    type: string
                scopes:
                  description: >-
                    Specify one or more fields (separated by commas) to search. Default: _id
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: A 200 status code indicates a successful query, and is accompanied by the query response payload.
      ## commenting out schemas and other status codes for now
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/QueryPOSTResult"
      #   '400':
      #     content:
      #       application/json:
      #         schema:
      #           "$ref": "#/components/schemas/ErrorResult"
      #     description: A response indicating an improperly formatted query
      # summary: Make batch gene queries and return matching gene hits
      tags:
      - query
      ## 2 operations
      x-bte-kgs-operations:
      - $ref: '#/components/x-bte-kgs-operations/protein-ligand'
      - $ref: '#/components/x-bte-kgs-operations/ligand-protein'
components:
  parameters:
    callback:
      name: callback
      description: >-
        Optional, you can pass a "callback" parameter to make a JSONP call.
      in: query
      required: false
      schema:
        type: string
    dotfield:
      name: dotfield
      description: >-
        Optional, can be used to control the format of the returned object. 
        If "dotfield" is true, the returned data object is returned flattened (no nested objects) 
        using dotfield notation for key names. Default: false.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    email:
      name: email
      description: >-
        Optional, if you are regular users of our services, we encourage you to provide us an email, 
        so that we can better track the usage or follow up with you.
      in: query
      required: false
      schema:
        type: string
    facet_size:
      name: facet_size
      description: >-
        Optional, an integer (1 <= facet_size <= 1000) that specifies how many buckets to return in a 
        [faceted query](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#faceted-queries).
      in: query
      required: false
      schema:
        type: integer
        default: 10
    facets:
      name: facets
      description: >-
        Optional, a single field or comma-separated fields to return facets, can only be used on non-free text fields. 
        E.g. “facets=chembl.molecule_properties.full_mwt”. See [examples of faceted queries for a core BioThings 
        API](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#faceted-queries).
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    fetch_all:
      name: fetch_all
      description: >-
        Optional, a boolean, which when TRUE, allows fast retrieval of all unsorted query hits. 
        The return object contains a _scroll_id field, which when passed as a parameter to the query endpoint 
        (see the scroll_id parameter), returns the next 1000 query results. Setting fetch_all = TRUE causes 
        the results to be inherently unsorted, therefore the sort parameter is ignored. For more information, 
        see [examples using fetch_all for a core BioThings 
        API](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#scrolling-queries). 
        Default: FALSE.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    fields:
      name: fields
      description: >-
        Optional, can be a comma-separated list to limit the fields returned from the object. 
        If "fields=all", all available fields will be returned.
        

        Note that it supports dot notation as well, e.g., you can pass "chebi.name". 
        Default: "fields=all". 
        The parameter "filter" is an alias for this parameter.
      in: query
      required: false
      schema:
        type: string
        default: all
    from:
      name: from
      description: >-
        Optional, the number of matching hits to skip, starting from 0. Default: 0. 
      in: query
      required: false
      schema:
        type: integer
        default: 0
    scroll_id:
      name: scroll_id
      description: >-
        Optional, a string containing the _scroll_id returned from a query request with fetch_all = TRUE. 
        Supplying a valid scroll_id will return the next 1000 unordered results. If the next results are 
        not obtained within 1 minute of the previous set of results, the scroll_id becomes stale, and a 
        new one must be obtained with another query request with fetch_all = TRUE. All other parameters are 
        ignored when the scroll_id parameter is supplied. For more information see [examples using scroll_id 
        for a core BioThings 
        API](https://docs.mychem.info/en/latest/doc/chem_query_service.html?highlight=from#scrolling-queries).
      in: query
      required: false
      schema:
        type: string
    size:
      name: size
      description: >-
        Optional, the maximum number of matching hits to return (with a cap of 1000 at the moment). Default: 10.
        The combination of "size" and "from" parameters can be used to get paging for a large query.
      in: query
      required: false
      schema:
        type: integer
        default: 10
    sort:
      name: sort
      description: >-
        Optional, the comma-separated fields to sort on. Prefix with "-" for descending order, otherwise in ascending order. 
        Default: sort by matching scores in descending order.
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    ## these are noted in the https://mychem.info/v1/spec endpoint; commenting out for now
    # _sorted:
    #   name: _sorted
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    #     default: true
    # aggs:
    #   name: aggs
    #   in: query
    #   required: false
    #   schema:
    #     type: array
    #     items:
    #       type: string
    # allow_null:
    #   name: allow_null
    #   in: query
    #   required: false
    #   schema:
    #     type: array
    #     items:
    #       type: string
    # always_list:
    #   name: always_list
    #   in: query
    #   required: false
    #   schema:
    #     type: array
    #     items:
    #       type: string
    # explain:
    #   name: explain
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    # format:
    #   name: format
    #   description: 'controls output format of server response, currently supports:
    #     "json", "jsonld", "html". Type: string. Default: json.'
    #   in: query
    #   required: false
    #   schema:
    #     type: string
    #     default: json
    # prefix:
    #   name: prefix
    #   in: query
    #   required: false
    #   schema:
    #     type: string
    # raw:
    #   name: raw
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    # rawquery:
    #   name: rawquery
    #   in: query
    #   required: false
    #   schema:
    #     type: boolean
    # search:
    #   name: search
    #   in: query
    #   required: false
    #   schema:
    #     type: string
    # userquery:
    #   name: userquery
    #   in: query
    #   required: false
    #   schema:
    #     type: string
  ## commenting out schemas and other status codes for now
  # schemas:
  #   Association:
  #     properties:
  #       _id:
  #         type: string
  #     required:
  #     - _id
  #     type: object
  #   ErrorResult:
  #     properties:
  #       message:
  #         type: string
  #       success:
  #         type: boolean
  #     type: object
  #   QueryPOSTResult:
  #     items:
  #       allOf:
  #       - $ref: '#/components/schemas/Association'
  #       - properties:
  #           _score:
  #             format: float
  #             type: number
  #           query:
  #             type: string
  #         type: object
  #     type: array
  #   QueryResult:
  #     properties:
  #       hits:
  #         items:
  #           $ref: '#/components/schemas/Association'
  #         type: array
  #       max_score:
  #         format: float
  #         type: number
  #       took:
  #         type: integer
  #       total:
  #         type: integer
  #     type: object
  #   int64_or_array:
  #     oneOf:
  #     - items:
  #         format: int64
  #         type: integer
  #       type: array
  #     - format: int64
  #       type: integer
  #   string_or_array:
  #     oneOf:
  #     - items:
  #         type: string
  #       type: array
  #     - type: string
  x-bte-kgs-operations:
    ## most (1413051 out of 1438909) documents in the API have a object.pubchem_cid field (all have the subject.uniprot.accession field). 
    ##     25,858 documents don't have object.pubchem_cid field so they currently aren't in the API
    ##     see analysis here https://github.com/biothings/pending.api/issues/70#issuecomment-1201574110
    ## other fields that are interesting, but seem overly detailed (so not included)
    ##   relation.ki_nm, relation.ic50_nm, relation.kd_nm, relation.ec50_nm, relation.kon, relation.koff, relation.ph, relation.temp_c, relation.num_protein_chains
    protein-ligand:
      - supportBatch: true
        useTemplating: true ## flag to say templating is being used below
        inputs:
          - id: UniProtKB
            semantic: Gene
        requestBody:
          body:
            ## API data has no prefix
            ## joinSafe is only needed if the delimiter isn't a comma
            q: "{{ queryInputs }}"
            scopes: subject.uniprot.accession
        outputs:
          - id: "PUBCHEM.COMPOUND"
            semantic: SmallMolecule
        parameters:
        ## commenting out because data-processing / biolink-modeling issues
        # ## only some documents have: subject.organism, relation.pmid, relation.article_doi, relation.patent_number
        #   fields: >-
        #     object.pubchem_cid,
        #     subject.name,subject.organism,
        #     relation.curation_datasource,relation.pmid,relation.bindingdb_link,relation.article_doi,relation.patent_number
          fields: >-
            object.pubchem_cid,
            subject.name,relation.pmid,relation.bindingdb_link,relation.article_doi
          size: 1000
        predicate: physically_interacts_with
        source: "infores:bindingdb"
        response_mapping:
          "$ref": "#/components/x-bte-response-mapping/pubchem-object"
        # testExamples:
        #   - qInput: "UniProtKB:P51681"                    ## C-C chemokine receptor type 5
        #     oneOutput: "PUBCHEM.COMPOUND:44401763"        ## (2R)-3-cyclobutyl-2-[(3S,4S)-3-phenyl-4-[[4-([1,2,4]triazolo[4,3-a]pyridin-3-yl)piperidin-1-yl]methyl]pyrrolidin-1-yl]propanoic acid 
    ligand-protein:
      - supportBatch: true
        useTemplating: true
        inputs:
          - id: "PUBCHEM.COMPOUND"
            semantic: SmallMolecule
        requestBody:
          body:
            q: "{{ queryInputs }}"
            scopes: object.pubchem_cid
        outputs:
          - id: UniProtKB
            semantic: Gene
        parameters:
        ## commenting out because data-processing / biolink-modeling issues
          # fields: >-
          #   subject.uniprot.accession,
          #   subject.name,subject.organism,
          #   relation.curation_datasource,relation.pmid,relation.bindingdb_link,relation.article_doi,relation.patent_number
          fields: >-
            subject.uniprot.accession,
            subject.name,relation.pmid,relation.bindingdb_link,relation.article_doi
          size: 1000
        predicate: physically_interacts_with
        source: "infores:bindingdb"
        response_mapping:
          "$ref": "#/components/x-bte-response-mapping/uniprot-subject"
        # testExamples:
        #   - qInput: "PUBCHEM.COMPOUND:134553288"     ## US10736883, Example 387.0
        #     oneOutput: "UniProtKB:P35414"            ## Apelin receptor
  x-bte-response-mapping:
  ## note on references:
  ##   sometimes the doi + pmid will refer to the same publication (so..."duplicate" references)
  ##   but there are plenty of cases where relationships have only 1 of these fields:
  ##   only doi: https://biothings.transltr.io/bindingdb/query?q=_exists_:relation.article_doi%20AND%20(NOT%20_exists_:relation.pmid)
  ##   only pmid: https://biothings.transltr.io/bindingdb/query?q=_exists_:relation.pmid%20AND%20(NOT%20_exists_:relation.article_doi)
    pubchem-object:
      "PUBCHEM.COMPOUND": object.pubchem_cid       ## no prefix
      "biolink:original_subject": subject.name     ## was called "Target Name Assigned by Curator or DataSource"
      ref_pmid: relation.pmid                          ## no prefix
      ref_doi: relation.article_doi
      ref_url: relation.bindingdb_link
      ## commenting out because data-processing / biolink-modeling issues
      # in_taxon: subject.organism                 ## was called "Target Source Organism According to Curator or DataSource"
      # bindingdb_curation_datasource: relation.curation_datasource    ## Curation/DataSource
      # patent_number: relation.patent_number
    uniprot-subject:
      UniProtKB: subject.uniprot.accession  ## no prefix
      "biolink:original_subject": subject.name
      ref_pmid: relation.pmid                          ## no prefix
      ref_doi: relation.article_doi
      ref_url: relation.bindingdb_link
      ## commenting out because data-processing / biolink-modeling issues
      # in_taxon: subject.organism
      # bindingdb_curation_datasource: relation.curation_datasource
      # patent_number: relation.patent_number