complete /api/evidence REST documentation

#%RAML 0.8
title: OpenBEL Platform
version: 0.0.2
baseUri: http://next.belframework.org/api
schemas:
  - annotation_resource:         !include http://next.belframework.org/schema/annotation_resource.schema.json
  - annotation_collection:       !include http://next.belframework.org/schema/annotation_collection.schema.json
  - annotation_value_resource:   !include http://next.belframework.org/schema/annotation_value_resource.schema.json
  - annotation_value_collection: !include http://next.belframework.org/schema/annotation_value_collection.schema.json
  - completion:                  !include http://next.belframework.org/schema/completion.schema.json
  - completion_collection:       !include http://next.belframework.org/schema/completion_collection.schema.json
  - evidence:                    !include http://next.belframework.org/schema/evidence.schema.json
  - evidence_resource:           !include http://next.belframework.org/schema/evidence_resource.schema.json
  - evidence_collection:         !include http://next.belframework.org/schema/evidence_collection.schema.json
  - match_result:                !include http://next.belframework.org/schema/match_result.schema.json
  - match_result_collection:     !include http://next.belframework.org/schema/match_result_collection.schema.json
traits:
  - ro_options:
      description: |
        Returns allowable HTTP methods for this <<name>>.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Allow:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'GET' ]
  - rw_options:
      description: |
        Returns allowable HTTP methods for this <<name>>.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Allow:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'GET', 'POST', 'PUT', 'DELETE' ]
  - create_options:
      description: |
        Returns allowable HTTP methods for this <<name>>.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Allow:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'GET', 'POST' ]
documentation:
  - title: Welcome
    content: |
      The OpenBEL Platform provides an Application Programming Interface (API) exposed over the Hypertext Transfer Protocol (HTTP). The primary goal of the API is to expose OpenBEL capabilities over the web to lower the technical barriers for users.
  - title: Functionality
    content: |
      The API provides the following:
      - Access and Search for BEL Annotations and Namespaces
      - Equivalence and Orthologize BEL expressions
      - Autocomplete syntax of BEL expressions
      - Access BEL Functions and Relationships
      - Store, query, and export BEL Evidence
  - title: Planned Functionality
    content: |
      We are currently working on the following:
      - Creating a group of BEL Evidence with returned resource "Location"
      - Support for [BEL version 2.0](http://wiki.openbel.org/display/BLVD)
      - Autocomplete with BEL expression semantics (e.g. namespace encoding, term signatures, etc.)
      - Creation of BEL knowledge networks from the Evidence collection
/api:
  description: |
    Root resource of the API. Lists all subresources contained within the API.
  options:
    is: [
      ro_options: { name: "root resource" }
    ]
  get:
    description: |
      Returns a list of linked *item* resources.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        body:
          application/hal+json:
            example: !include examples/root.example.json
/annotations:
  description: |
    Annotation collection within the API.

    This provides access to BEL annotation vocabularies such as MeSH, Gene Ontology, and Disease Ontology.

    BEL Evidence can be annotated to express knowledge about the evidence itself. Some important uses of annotations are:
      - Specify information about the biological system in which the facts represented by the statement hold or were demonstrated.
      - Specify information about the experimental methods used to demonstrate the facts.
      - Specify information about the knowledge source on which the statement is based, such as the citation and the specific text supporting the statement.
  options:
    is: [
      ro_options: { name: "annotation_collection" }
    ]
  get:
    description: |
      Returns the *annotation_collection* containing an array of all *annotation* resources.

      An *annotation* resource contains fields:
      - prefLabel: human-readable name
      - prefix:    short prefix
      - domain:    biological domain
      -

      The collection contains zero or more *annotation* resource objects. If the *annotation_collection* is empty then the result is an empty array.

    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

          **JSON Schema**
          - [annotation_collection](schemas/annotation_collection.schema.json)
          - [annotation](schemas/annotation_resource.schema.json)
        body:
          application/json:
            example: !include examples/annotation_collection.example.json
  /values:
    description: |
      Annotation Value collection for all Annotation resources within the API.

      This provides a collection of all BEL annotation values that can be listed and filtered.
    options:
      is: [
        ro_options: { name: "annotation_value_collection" }
      ]
    get:
      description: |
        Returns the *annotation_value_collection* across all *annotation* resources.

        Example: *Search by filter*

         **Limitations**

         This endpoint is limited to full-text searching including a *filter* like:
         ```json
         {
             "category": "fts",
             "name":     "search",
             "value":    "sarcoma"
         }
         ```

        **Complete Example**

        **GET http://next.belframework.org/api/annotations/values?filter={%22category%22:%22fts%22,%22name%22:%22search%22,%22value%22:%22sarcoma%22}&start=0&size=3**

        ```json
        {
          "annotation_value_collection": [
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "D012509",
                "name": "Sarcoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases/values/D012509"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases"
                  }
                }
              }
            },
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "1115",
                "name": "sarcoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology/values/1115"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology"
                  }
                }
              }
            },
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "D008223",
                "name": "Lymphoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases/values/D008223"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases"
                  }
                }
              }
            }
          ]
        }
        ```

      queryParameters:
        start:
          type: integer
          description: |
            The annotation value resource to start from for paging purposes.
          example:  "0"
          required: false
        size:
          type: integer
          description: |
            The size of the annotation value resource collection to retrieve. This will return a slice of the annotation value resource collection relative to *start*.

            A size of zero or less will return all values.
          example:  3
          required: false
        filter:
          type: string
          description: |
            A filter to apply to the annotation value resource collection to narrow the resources retrieved.
          example: |
            {"category":"fts","name":"search","value":"sarcoma"}
          required: false
        faceted:
          type: string
          description: |
            The boolean indicator to provided faceted results for the annotation value resource collection. The default is to not facet.
          enum: [ 'true', 'yes', '1', 'on' ]
          example: no
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

            **JSON Schema**
            - [annotation_value_collection](schemas/annotation_value_collection.schema.json)
            - [annotation_value](schemas/annotation_value_resource.schema.json)
          body:
            application/json:
              example: !include examples/annotation_values_filter.example.json
        400:
          description: |
            [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1)

            Returned if a filter is malformed.
        404:
          description: |
            [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

            Returned if no annotation values were found for the FTS search.

            Returned if a `{"category":"fts", "name": "search", ...}` filter was not provided.
        501:
          description: |
            [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2)

            Returned if the client enabled the `faceted` query parameter. This is currently not implemented.
  /{annotation}:
    description: |
      Annotation resource identified by *{annotation}* URI parameter.
    uriParameters:
      annotation:
        type: string
        description: |
          An identifier string for an annotation. This is either the annotation prefix, name, or URI part.
        example: |
          "do" or "Disease Ontology" or "disease-ontology" (all resolve to the same annotation resource)
        required: true
    options:
      is: [
        ro_options: { name: "annotation resource" }
      ]
    get:
      description: |
        Returns the *annotation* resource identified by *{annotation}* URI parameter.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

            **JSON Schema**
            - [annotation](schemas/annotation_resource.schema.json)
          body:
            application/json:
              example: !include examples/annotation_resource.example.json
    /values:
      description: |
        Annotation Value collection within an Annotation resource identified by *{annotation}*.
      options:
        is: [
          ro_options: { name: "annotation_value_collection" }
        ]
      get:
        description: |
          Returns the *annotation_value_collection* across the *annotation* resource identified by *{annotation}* URI parameter.

          Example: *Search by filter*

           **Limitations**

           This endpoint is limited to full-text searching including a *filter* like:
           ```json
           {
               "category": "fts",
               "name":     "search",
               "value":    "sarcoma"
           }
           ```

          **Complete Example**

          **GET http://next.belframework.org/api/annotations/do/values?filter={%22category%22:%22fts%22,%22name%22:%22search%22,%22value%22:%22sarcoma%22}&start=0&size=3**

          ```json
          {
            "annotation_value_collection": [
              {
                "annotation_value": {
                  "type": "BiologicalProcessConcept",
                  "identifier": "1115",
                  "name": "sarcoma",
                  "_links": {
                    "self": {
                      "type": "annotation_value",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology/values/1115"
                    },
                    "collection": {
                      "type": "annotation",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology"
                    }
                  }
                }
              },
              {
                "annotation_value": {
                  "type": "BiologicalProcessConcept",
                  "identifier": "3071",
                  "name": "gliosarcoma",
                  "_links": {
                    "self": {
                      "type": "annotation_value",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology/values/3071"
                    },
                    "collection": {
                      "type": "annotation",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology"
                    }
                  }
                }
              },
              {
                "annotation_value": {
                  "type": "BiologicalProcessConcept",
                  "identifier": "3382",
                  "name": "liposarcoma",
                  "_links": {
                    "self": {
                      "type": "annotation_value",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology/values/3382"
                    },
                    "collection": {
                      "type": "annotation",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology"
                    }
                  }
                }
              }
            ]
          }
          ```
        queryParameters:
          start:
            type: integer
            description: |
              The annotation value resource to start from for paging purposes.
            example:  "0"
            required: false
          size:
            type: integer
            description: |
              The size of the annotation value resource collection to retrieve. This will return a slice of the annotation value resource collection relative to *start*.

              A size of zero or less will return all values.
            example:  3
            required: false
          filter:
            type: string
            description: |
              A filter to apply to the annotation value resource collection to narrow the resources retrieved.
            example: |
              {"category":"fts","name":"search","value":"sarcoma"}
            required: false
          faceted:
            type: string
            description: |
              The boolean indicator to provided faceted results for the annotation value resource collection. The default is to not facet.
            enum: [ 'true', 'yes', '1', 'on' ]
            example: no
        responses:
          200:
            description: |
              [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

              **JSON Schema**
              - [annotation_value_collection](schemas/annotation_value_collection.schema.json)
            body:
              application/json:
                example: !include examples/annotation_value_collection.example.json
          400:
            description: |
              [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1)

              Returned if a filter is malformed.
          404:
            description: |
              [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

              Returned if no annotation values were found for the FTS search.

              Returned if a `{"category":"fts", "name": "search", ...}` filter was not provided.
          501:
            description: |
              [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2)

              Returned if the client enabled the `faceted` query parameter. This is currently not implemented.
      /{value}:
        description: |
          Annotation value resource identified by *{annotation}* and *{value}* URI parameters.
        options:
          is: [
            ro_options: { name: "annotation_value resource" }
          ]
        get:
          description: |
            Returns the *annotation_value* resource identified by *{annotation}* and *{value}* URI parameters.

            **Complete Example**

            **GET http://next.belframework.org/api/annotations/do/values/sarcoma**

            ```json
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "1115",
                "name": "sarcoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology/values/1115"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology"
                  }
                }
              }
            }
            ```
          responses:
            200:
              description: |
                [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

                **JSON Schema**
                - [annotation_value](schemas/annotation_value_resource.schema.json)
              body:
                application/json:
                  example: !include examples/annotation_value_resource.example.json
            404:
              description: |
                [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

                Returned if a resource was not found by *{annotation}* and *{value}*.
/evidence:
  description: |
    Evidence collection within the API.

    This provides storage and query of Evidence resources.

    BEL Evidence represents a biological finding extracted from scientific literature. It is comprised of 5 parts:
      - Citation

        Identifies the reference (e.g. PubMed, Book, Journal, etc.) that contains supporting the *Summary Text*.

      - Summary Text

        The excerpt from the *Citation* that the *BEL Statement* is extracted from.

      - BEL Statement

        An expression that represents knowledge of the existence of biological entities and relationships between them that are known to be observed within a particular *Experiment Context*. The structure of a BEL Statement is explained further on the [OpenBEL Wiki](http://wiki.openbel.org/display/BLVD/Statements).

      - Experiment Context

        Data (Key/Value) that describes parameters of the experiment. For example an evidence observed in the lung of a human could include Uberon's *lung* concept (i.e. [uberon/UBERON:0002048](http://identifiers.org/uberon/UBERON:0002048)) and NCBI Taxonomy's *homo sapiens* concept (i.e. [taxonomy/9606](http://identifiers.org/taxonomy/9606)) respectively.

      - Metadata

        Data (Key/Value) about this evidence resource useful for bookkeeping or system integration purposes. For example one might want to capture a *Reviewer* and *Review Status* to track who is reviewing and this evidence's status respectively.

      - References

        States the vocabularies which the namespace and annotation values are drawn from. Each vocabulary should include a keyword and URI.

  options:
    is: [
      create_options: { name: "evidence collection" }
    ]
  post:
    description: |
      Creates one or more Evidence resource within the API.

      The following formats are supported:
      - Evidence JSON
        - media type:  `application/json`
        - JSON schema: [evidence.schema.json](http://next.belframework.org/schema/evidence.schema.json)
      - BEL Script
        - defined by [BEL Script V1.0 Format](http://wiki.openbel.org/display/BLDV20/BEL+Script+V1.0+Format)
        - media type: `application/bel`
      - XBEL (XML)
        - media type: `application/xml`
        - XML Schema: [xbel](http://resource.belframework.org/belframework/20150611/schema/xbel.xsd), [xbel-annotations](http://resource.belframework.org/belframework/20150611/schema/xbel-annotations.xsd)
      - [BEL JSON Graph Format](http://jsongraphformat.info/)
        - media type:  `application/vnd.jgf+json`
        - JSON schema: [bel-json-graph-2.0.schema.json](http://jsongraphformat.info/child-schemas/bel-json-graph-2.0.schema.json)
      - BEL RDF
        - defined within [bel.rb](https://github.com/OpenBEL/bel.rb) as a [format extension](https://github.com/OpenBEL/bel.rb/wiki/Format-Extensions). See [source](https://github.com/OpenBEL/bel.rb/tree/c1471942ce8326ad2399d66154c858d6a9fbcd6b/lib/bel/extensions/rdf)
        - media type
          - `application/n-quads`
          - `application/n-triples`
          - `application/rdf+xml`
          - `application/turtle`
          - `application/x-turtle`
          - `text/turtle`

      If you send a single Evidence JSON object then the resource's *Location* will be returned. However if you send multiple Evidence resources using any of the supported formats above then a *Location* will not be returned. This will be addressed in a future version.

    responses:
      201:
        description: |
          [201 Created](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2)

          The Evidence resource was created.

          The link to the evidence resource is conveyed is the *Link* header. This will only be set when a single Evidence resource is created.
      415:
        description: |
          [415 Unsupported Media Type](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16)

          The evidence resource body was not a supported media type..
    body:
      application/json:
        example: |
          {
            "evidence": {
              "bel_statement": "p(HGNC:MAPK1,pmod(P,T)) => kin(p(HGNC:MAPK1))",
              "citation": {
                "type": "PubMed",
                "name": "J Biol Chem. 1997 Jul 4;272(27):16917-23.",
                "id": "9202001"
              },
              "summary_text": "These kinases are regulated by the reversible dual\nphosphorylation of conserved threonine and tyrosine residues.",
              "experiment_context": [
                {
                  "name": "Species",
                  "value": "9606",
                  "uri": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno/9606",
                  "url": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"
                },
                {
                  "name": "CellLine",
                  "value": "U-937",
                  "uri": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno/U-937",
                  "url": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
                }
              ],
              "references": {
                "namespaces": {
                  "SFAM": "http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns",
                  "SCOMP": "http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns",
                  "HGNC": "http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns",
                  "CHEBI": "http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"
                },
                "annotations": {
                  "CellLine": {
                    "type": "url",
                    "domain": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
                  },
                  "Species": {
                    "type": "url",
                    "domain": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"
                  }
                }
              },
              "metadata": [
                {
                  "name": "document_header",
                  "value": {
                    "Name": "BEL Framework Example 1 Document",
                    "Description": "Example of modeling a full abstract taken from the BEL V1.0 Language Overview. ",
                    "Version": "20150611",
                    "Copyright": "Copyright (c) 2011-2015, Selventa. All Rights Reserved.",
                    "ContactInfo": "support@belframework.org",
                    "Authors": "Selventa",
                    "Licenses": "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License"
                  }
                }
              ]
            }
          }

      application/bel:
        example: |
          SET DOCUMENT Name = "BEL Framework Example 1 Document"
          SET DOCUMENT Description = "Example of modeling a full abstract taken from the BEL V1.0 Language Overview. "
          SET DOCUMENT Version = "20150611"
          SET DOCUMENT Copyright = "Copyright (c) 2011-2015, Selventa. All Rights Reserved."
          SET DOCUMENT ContactInfo = "support@belframework.org"
          SET DOCUMENT Authors = "Selventa"
          SET DOCUMENT Licenses = "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License"

          DEFINE NAMESPACE SFAM AS URL "http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns"
          DEFINE NAMESPACE SCOMP AS URL "http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns"
          DEFINE NAMESPACE HGNC AS URL "http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns"
          DEFINE NAMESPACE CHEBI AS URL "http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"

          DEFINE ANNOTATION CellLine AS URL "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
          DEFINE ANNOTATION Species AS URL "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"

          SET Citation = {"PubMed","J Biol Chem. 1997 Jul 4;272(27):16917-23.","9202001"}
          SET Evidence = "These kinases are regulated by the reversible dual
          SET Species = "9606"
          SET CellLine = "U-937"
          p(HGNC:MAPK1,pmod(P,T)) => kin(p(HGNC:MAPK1))

      application/xml:
        example: |
          &lt?xml version="1.0"?&gt
          &ltbel:document xmlns:bel="http://belframework.org/schema/1.0/xbel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://belframework.org/schema/1.0/xbel http://resource.belframework.org/belframework/1.0/schema/xbel.xsd"&gt
            &ltbel:header&gt
              &ltbel:name&gtBEL Framework Example 1 Document&lt/bel:name&gt
              &ltbel:description&gtExample of modeling a full abstract taken from the BEL V1.0 Language Overview. &lt/bel:description&gt
              &ltbel:version&gt20150611&lt/bel:version&gt
              &ltbel:copyright&gtCopyright (c) 2011-2015, Selventa. All Rights Reserved.&lt/bel:copyright&gt
              &ltbel:contactInfo&gtsupport@belframework.org&lt/bel:contactInfo&gt
              &ltbel:authorGroup&gt
                &ltbel:author&gtSelventa&lt/bel:author&gt
              &lt/bel:authorGroup&gt
              &ltbel:licenseGroup&gt
                &ltbel:license&gtCreative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License&lt/bel:license&gt
              &lt/bel:licenseGroup&gt
            &lt/bel:header&gt
            &ltbel:namespaceGroup&gt
              &ltbel:namespace bel:prefix="SFAM" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns"/&gt
              &ltbel:namespace bel:prefix="SCOMP" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns"/&gt
              &ltbel:namespace bel:prefix="HGNC" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns"/&gt
              &ltbel:namespace bel:prefix="CHEBI" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"/&gt
            &lt/bel:namespaceGroup&gt
            &ltbel:annotationDefinitionGroup&gt
              &ltbel:externalAnnotationDefinition bel:id="CellLine" bel:url="http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"/&gt
              &ltbel:externalAnnotationDefinition bel:id="Species" bel:url="http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"/&gt
            &lt/bel:annotationDefinitionGroup&gt
            &ltbel:statementGroup&gt
              &ltbel:statement bel:relationship="=>"&gt
                &ltbel:annotationGroup&gt
                  &ltbel:citation bel:type="PubMed"&gt
                    &ltbel:reference&gt9202001&lt/bel:reference&gt
                    &ltbel:name&gtJ Biol Chem. 1997 Jul 4;272(27):16917-23.&lt/bel:name&gt
                  &lt/bel:citation&gt
                  &ltbel:evidence&gtThese kinases are regulated by the reversible dual
          phosphorylation of conserved threonine and tyrosine residues.&lt/bel:evidence&gt
                  &ltbel:annotation bel:refID="Species"&gt9606&lt/bel:annotation&gt
                  &ltbel:annotation bel:refID="CellLine"&gtU-937&lt/bel:annotation&gt
                &lt/bel:annotationGroup&gt
                &ltbel:subject&gt
                  &ltbel:term bel:function="proteinAbundance"&gt
                    &ltbel:parameter bel:ns="HGNC"&gtMAPK1&lt/bel:parameter&gt
                    &ltbel:term bel:function="proteinModification"&gt
                      &ltbel:parameter&gtP&lt/bel:parameter&gt
                      &ltbel:parameter&gtT&lt/bel:parameter&gt
                    &lt/bel:term&gt
                  &lt/bel:term&gt
                &lt/bel:subject&gt
                &ltbel:object&gt
                  &ltbel:term bel:function="kinaseActivity"&gt
                    &ltbel:term bel:function="proteinAbundance"&gt
                      &ltbel:parameter bel:ns="HGNC"&gtMAPK1&lt/bel:parameter&gt
                    &lt/bel:term&gt
                  &lt/bel:term&gt
                &lt/bel:object&gt
              &lt/bel:statement&gt
            &lt/bel:statementGroup&gt
          &lt/bel:document&gt

      application/vnd.jgf+json:
        example: |
          {
            "graph": {
              "type": "BEL-V1.0",
              "nodes": [
                {
                  "id": "p(HGNC:MAPK1,pmod(P,T))",
                  "label": "p(HGNC:MAPK1,pmod(P,T))"
                },
                {
                  "id": "kin(p(HGNC:MAPK1))",
                  "label": "kin(p(HGNC:MAPK1))"
                }
              ],
              "edges": [
                {
                  "source": "p(HGNC:MAPK1,pmod(P,T))",
                  "relation": "=>",
                  "target": "kin(p(HGNC:MAPK1))"
                }
              ]
            }
          }

      application/n-triples:
        example: |
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/ModifiedProteinAbundance&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1,pmod(P,T))" .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.openbel.org/vocabulary/hasModificationType&gt &lthttp://www.openbel.org/vocabulary/Phosphorylation&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.openbel.org/vocabulary/hasChild&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/ProteinAbundance&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1)" .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasConcept&gt &lthttp://www.openbel.org/bel/namespace/hgnc-human-genes/MAPK1&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/AbundanceActivity&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasActivityType&gt &lthttp://www.openbel.org/vocabulary/Kinase&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "kin(p(HGNC:MAPK1))" .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasChild&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/ProteinAbundance&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1)" .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasConcept&gt &lthttp://www.openbel.org/bel/namespace/hgnc-human-genes/MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasSubject&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasObject&gt &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasRelationship&gt &lthttp://www.openbel.org/vocabulary/DirectlyIncreases&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Statement&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1,pmod(P,T)) =&gt kin(p(HGNC:MAPK1))" .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Evidence&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasEvidence&gt _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasStatement&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasCitation&gt &lthttp://bio2rdf.org/pubmed:9202001&gt .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasEvidenceText&gt "These kinases are regulated by the reversible dual\nphosphorylation of conserved threonine and tyrosine residues." .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasAnnotation&gt &lthttp://www.openbel.org/bel/annotation/species-taxonomy-id/9606&gt .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasAnnotation&gt &lthttp://www.openbel.org/bel/annotation/cell-line/U-937&gt .

  get:
    description: |
      Retrieve the evidence resource collection.

      All evidence resources will be returned by default.

      The collection can be returned page by page by providing a *start* (defaults to `0`) index and *size* (defaults to no size limit) to return.

      This collection can be filtered by providing one or more *filter* options. A filter specifies the *category*, *name*, and *value* of the filter and is encoded as a JSON object. For example an evidence metadata filter might be encoded as:

      ```json
        {
          "category": "metadata",
          "name": "status",
          "value": "Approved"
        }
      ```

      This collection can be filtered using by a full-text search filter such as:

      ```json
        {
          "category": "fts",
          "name": "search",
          "value": "lung liver pancreas"
        }
      ```

      ```json
        {
          "category": "fts",
          "name": "search",
          "value": "\"subdural hematoma\""
        }
      ```

      This collection can specify the *faceted* boolean option. Facets will reflect all (possibly filtered) evidence resources irrespective of *start* and *size* paging.

      Facts are an array of facet objects that are composed of a *filter* and *count*. For example for the evidence metadata filter the facet object would be encoded as:

      ```json
        {
          "category": "metadata",
          "name": "Status",
          "values": [
            {
              "value": "Approved",
              "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Approved\"}",
              "count": 10200
            }
          ]
        },
      ```

      The *filter* property value can be used as a *filter* option. This is intended to support filtering the evidence resource collection by selected facets.

      The *max_values_per_facet* option can be specified to limit the number of returned facet values by category, name pairs. For example, setting *max_values_per_facet* to `2` would return up to 2 distinct facets values for `{ "category": "citation", "name": "id", ... }`.
    headers:
      Accept:
        displayName: Accept
        description: |
          The Accept header informs the server which media types the client accepts.
    queryParameters:
      start:
        type: integer
        description: |
          The evidence resource to start from for paging purposes.

          The default value is `0`. This value will return evidence resources starting from the beginning of collection.
        example: 100
        required: false
      size:
        type: integer
        description: |
          The size of the evidence resource collection to retrieve. This will return a slice of the evidence resource collection relative to *start*.

          The default is `0`. This value will return all evidence resources in the collection.
        example: 100
        required: false
      filter:
        type: string
        description: |
          A filter to apply to the evidence resource collection to narrow the resources retrieved.

          The default is to not apply filters. If filters are not specified then all evidence resources, in the collection, will be returned.
        example: |
          {"category":"experiment_context","name":"Anatomy","value":"prostate gland"}
          {"category":"fts","name":"search","value":"\"subdural hematoma\" carcinoma"}
          {"category":"fts","name":"search","value":"homatoma -carcinoma"}
        required: false
      faceted:
        type: string
        description: |
          The boolean indicator to provided faceted results for the evidence resource collection.

          The default is `false`. This value will not return facets in the response.
        enum: [ 'true', 'yes', '1', 'on' ]
        example: yes
      max_values_per_facet:
        type: integer
        description: e|
          The maximum about of facet values to display for every category, name pair.

          The default is `0`. This value will return all facet values (i.e. unbounded) for every category, name pair.
        example: 20
        required: false
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

          An example request for this resource might be:

          - Path: `/api/evidence`
          - Query parameters:
            - `start=0`
            - `size=1`
            - `faceted=yes`
            - `max_values_per_facet=1`
            - `filter`
            ```json
            {
              "category":"experiment_context",
              "name":"Anatomy",
              "value":"prostate gland"
            }
            ```

          Example URL: [http://next.belframework.org/api/evidence?start=0&size=1&faceted=yes&max_values_per_facet=1&filter={"category":"experiment_context","name":"Anatomy","value":"prostate gland"}](http://next.belframework.org/api/evidence?start=0&size=1&faceted=yes&max_values_per_facet=1&filter={%22category%22:%22experiment_context%22,%22name%22:%22Anatomy%22,%22value%22:%22prostate gland%22})

          **JSON Schema**
          - [evidence_collection](schemas/evidence_collection.schema.json)
          - [evidence_resource](schemas/evidence_resource.schema.json)
          - [evidence](schemas/evidence.schema.json)

        body:
          application/json:
            example: |
              {
                "evidence_collection": [
                  {
                    "evidence": {
                      "bel_statement": "a(CHEBI:\"1-octadec-9-enoylglycero-3-phosphate\") increases kin(p(HGNC:EGFR))",
                      "citation": {
                        "type": "PubMed",
                        "name": "Exp Cell Res 2003 Mar 10 284(1) 99-110",
                        "id": "12648469",
                        "date": "",
                        "authors": [],
                        "comment": ""
                      },
                      "summary_text": "Treatment of cells with GPCR agonists such as endothelin- 1 (ET-1), thrombin, bombesin, and lysophosphatidic acid (LPA) transactivates ErbB1 (reviewed by Zwick et al. [48]). Mechanistically, the process involves rapid stimulation of metalloproteinases followed by cleavage of an ErbB1 ligand precursor, e.g., pro-HB-EGF [49], whose binding activates ErbB1 and downstream signaling pathways",
                      "experiment_context": [
                        {
                          "name": "Species",
                          "value": "9606"
                        },
                        {
                          "name": "Anatomy",
                          "value": "prostate gland"
                        },
                        {
                          "name": "Cell",
                          "value": "squamous epithelial cell"
                        }
                      ],
                      "metadata": [
                        {
                          "name": "document_header",
                          "value": {
                            "Name": "BEL Framework Large Corpus Document",
                            "Description": "Approximately 61,000 statements.",
                            "Version": "20150611",
                            "Copyright": "Copyright (c) 2011-2015, Selventa. All rights reserved.",
                            "Authors": "Selventa",
                            "Licenses": "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License",
                            "ContactInfo": "support@belframework.org"
                          }
                        }
                      ]
                    },
                    "_links": {
                      "self": {
                        "type": "evidence",
                        "href": "http://next.belframework.org/api/evidence/56015a638a4cca1317005637"
                      },
                      "collection": {
                        "type": "evidence_collection",
                        "href": "http://next.belframework.org/api/evidence"
                      }
                    }
                  }
                ],
                "facets": [
                  {
                    "category": "metadata",
                    "name": "document_header",
                    "values": [
                      {
                        "value": [
                          "Authors",
                          "Selventa"
                        ],
                        "filter": "{\"category\":\"metadata\",\"name\":\"document_header\",\"value\":[\"Authors\",\"Selventa\"]}",
                        "count": 423
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Anatomy",
                    "values": [
                      {
                        "value": "prostate gland",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}",
                        "count": 423
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Species",
                    "values": [
                      {
                        "value": "9606",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Species\",\"value\":\"9606\"}",
                        "count": 263
                      }
                    ]
                  },
                  {
                    "category": "citation",
                    "name": "id",
                    "values": [
                      {
                        "value": "12351634",
                        "filter": "{\"category\":\"citation\",\"name\":\"id\",\"value\":\"12351634\"}",
                        "count": 62
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Cell",
                    "values": [
                      {
                        "value": "fibroblast",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Cell\",\"value\":\"fibroblast\"}",
                        "count": 20
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Cellline",
                    "values": [
                      {
                        "value": "LNCAP cell",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Cellline\",\"value\":\"LNCAP cell\"}",
                        "count": 17
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Disease",
                    "values": [
                      {
                        "value": "prostate carcinoma in situ",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Disease\",\"value\":\"prostate carcinoma in situ\"}",
                        "count": 13
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Cellstructure",
                    "values": [
                      {
                        "value": "Cytoplasm",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Cellstructure\",\"value\":\"Cytoplasm\"}",
                        "count": 4
                      }
                    ]
                  }
                ],
                "metadata": {
                  "collection_paging": {
                    "total": 52399,
                    "total_filtered": 423,
                    "total_pages": 423,
                    "current_page": 1,
                    "current_page_size": 1
                  }
                },
                "_links": {
                  "self": {
                    "type": "evidence_collection",
                    "href": "http://next.belframework.org/api/evidence?start=0&size=1&filter={\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}"
                  },
                  "start": {
                    "type": "evidence_collection",
                    "href": "http://next.belframework.org/api/evidence?start=0&size=1&filter={\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}"
                  },
                  "next": {
                    "type": "evidence_collection",
                    "href": "http://next.belframework.org/api/evidence?start=1&size=1&filter={\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}"
                  }
                }
              }
      404:
        description: |
          [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

          The evidence collection could not be found given your request. This typically indicates an empty evidence collection for the provided query parameters.
      406:
        description: |
          [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7)

          The evidence collection identified cannot be returned in the client-specified Content Type.
  /{identifier}:
    description:
    options:
      is: [
        rw_options: { name: "evidence resource" }
      ]
    get:
      description: |
        Retrieve the Evidence resource identified by *{identifier}*.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

            An example request for this resource might be:

            - Path: `/api/evidence/56015c7e8a4cca1317006aa7`

            Example URL: [http://next.belframework.org/api/evidence/56015c7e8a4cca1317006aa7](http://next.belframework.org/api/evidence/56015c7e8a4cca1317006aa7)

            **JSON Schema**
            - [evidence_resource](schemas/evidence_resource.schema.json)
            - [evidence](schemas/evidence.schema.json)

          body:
            application/json:
              example: |
                {
                  "evidence": {
                    "bel_statement": "a(\"cyclic AMP\") increases r(HGNC:AR)",
                    "citation": {
                      "type": "PubMed",
                      "name": "J Clin Endocrinol Metab 2003 Sep 88(9) 4043-54",
                      "id": "12970260",
                      "date": "",
                      "authors": [],
                      "comment": ""
                    },
                    "summary_text": "Treatment with the cAMP analog dibutyryl cAMP enhanced AR promoter activity about 4- to 6-fold in a reporter gene assay and increased AR mRNA expression in LNCaP cells",
                    "experiment_context": [
                      {
                        "name": "Species",
                        "value": "9606"
                      }
                    ],
                    "metadata": [
                      {
                        "name": "document_header",
                        "value": {
                          "Name": "BEL Framework Large Corpus Document",
                          "Description": "Approximately 61,000 statements.",
                          "Version": "20150611",
                          "Copyright": "Copyright (c) 2011-2015, Selventa. All rights reserved.",
                          "Authors": "Selventa",
                          "Licenses": "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License",
                          "ContactInfo": "support@belframework.org"
                        }
                      }
                    ]
                  },
                  "_links": {
                    "self": {
                      "type": "evidence",
                      "href": "http://next.belframework.org/api/evidence/56015c7e8a4cca1317006aa7"
                    },
                    "collection": {
                      "type": "evidence_collection",
                      "href": "http://next.belframework.org/api/evidence"
                    }
                  }
                }
        404:
          description: |
            [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

            The evidence resource could not be found for the given *{identifier}*.
        406:
          description: |
            [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7)

            The evidence resource identified cannot be returned in the client-specified Content Type.
    put:
      description: |
        Replaces an Evidence resource identified by *{identifier}*.

        **JSON Schema**
        - [evidence_resource](schemas/evidence_resource.schema.json)
        - [evidence](schemas/evidence.schema.json)
      body:
        application/json:
          example: |
            {
              "evidence": {
                "bel_statement": "p(HGNC:MAPK1,pmod(P,T)) => kin(p(HGNC:MAPK1))",
                "citation": {
                  "type": "PubMed",
                  "name": "J Biol Chem. 1997 Jul 4;272(27):16917-23.",
                  "id": "9202001"
                },
                "summary_text": "These kinases are regulated by the reversible dual\nphosphorylation of conserved threonine and tyrosine residues.",
                "experiment_context": [
                  {
                    "name": "Species",
                    "value": "9606",
                    "uri": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno/9606",
                    "url": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"
                  },
                  {
                    "name": "CellLine",
                    "value": "U-937",
                    "uri": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno/U-937",
                    "url": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
                  }
                ],
                "references": {
                  "namespaces": {
                    "SFAM": "http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns",
                    "SCOMP": "http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns",
                    "HGNC": "http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns",
                    "CHEBI": "http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"
                  },
                  "annotations": {
                    "CellLine": {
                      "type": "url",
                      "domain": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
                    },
                    "Species": {
                      "type": "url",
                      "domain": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"
                    }
                  }
                },
                "metadata": [
                  {
                    "name": "document_header",
                    "value": {
                      "Name": "BEL Framework Example 1 Document",
                      "Description": "Example of modeling a full abstract taken from the BEL V1.0 Language Overview. ",
                      "Version": "20150611",
                      "Copyright": "Copyright (c) 2011-2015, Selventa. All Rights Reserved.",
                      "ContactInfo": "support@belframework.org",
                      "Authors": "Selventa",
                      "Licenses": "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License"
                    }
                  }
                ]
              }
            }
      responses:
        202:
          description: |
            [202 Accepted](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3)

            The action to replace the evidence resource, identified by *{identifier}*, was accepted by the API. The evidence resource is considered replaced if a subsequent `GET /api/evidence/{identifier}` request returns a representation that reflects the body sent in this `PUT` request.
        404:
          description: |
            [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

            The evidence resource, identified by *{identifier}*, does not exist.
        415:
          description: |
            [415 Unsupported Media Type](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16)

            The evidence resource body was not a supported media type.
    delete:
      description: |
        Deletes an Evidence resource identified by *{identifier}*.
      responses:
        202:
          description: |
            [202 Accepted](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3)

            The action to delete the evidence resource, identified by *{identifier}*, was accepted by the API. The evidence resource is considered removed if a subsequent `GET /api/evidence/{identifier}` request returns [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5).
        404:
          description: |
            [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

            The evidence resource, identified by *{identifier}*, does not exist.
/expressions:
  /{bel}/completions:
    description: |
      Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

      Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

      Custom Caret Position:

      The caret position can be provided to indicate where to complete from.

      Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
    uriParameters:
      bel:
        type: string
        description: BEL statement fragment; Completions will be provided for this input.
        required: false
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    get:
      description: |
        Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

        Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

        Custom Caret Position:

        The caret position can be provided to indicate where to complete from.

        Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
      headers:
        Accept:
          displayName: Accept
      queryParameters:
        caret_position:
          type: integer
          description: The position of the caret within the *bel* input. Defaults to the right-most caret_position for *bel* (e.g. length of *bel* input).
          example: 0
          required: false
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          body:
            application/json:
              example: |
                {
                  "completions": [
                    {
                      "type": "namespace_prefix",
                      "label": "HGNC",
                      "value": "HGNC:",
                      "highlight": {
                        "start_position": 2,
                        "end_position": 3,
                        "range_type": "inclusive"
                      },
                      "actions": [
                        {
                          "delete": {
                              "start_position": 2,
                              "end_position": 3,
                              "range_type": "inclusive"
                          },
                          "insert": {
                              "position": 2,
                              "value": "HGNC:"
                          },
                          "move_cursor": {
                              "position": 7
                          }
                        }
                      ]
                    }
                  ]
                }
              schema: completion_collection
  /{bel}/components:
    description: |
      Retrieve the components of a *BEL* expression fragment. Currently this will only return the *subject*, *relationship*, and *object* understood from BEL statement expression.
    uriParameters:
      bel:
        type: string
        description: BEL statement expression to recognize; Components will be returned for this input.
        required: false
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    get:
      description: |
        Retrieve the components of a *BEL* expression fragment. Currently this will only return the *subject*, *relationship*, and *object* understood from BEL statement expression.

        Examples:

          - *p(HGNC:AKT1)* yields:

            ```json
            {
                "expression_components": {
                    "subject":      "p(HGNC:AKT1)",
                    "relationship": null,
                    "object":       null
                }
            }
            ```

          - *p(HGNC:AKT1) -> bp(MESHPP:Apoptosis)* yields:

            ```json
            {
                "expression_components": {
                    "subject":      "p(HGNC:AKT1)",
                    "relationship": "increases",
                    "object":       "bp(MESHPP:Apoptosis)"
                }
            }
            ```

          - *a(CHEBI:"phosphatidyl-L-serine") increases pep(p(HGNC:F3))* yields:

            ```json
            {
                "expression_components": {
                    "subject":      "a(CHEBI:\"phosphatidyl-L-serine\")",
                    "relationship": "increases",
                    "object":       "pep(p(HGNC:F3))"
                }
            }
            ```

      queryParameters:
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          body:
            application/json:
              example: |
                {
                    "expression_components": {
                        "subject":      "p(HGNC:AKT1)",
                        "relationship": "increases",
                        "object":       "bp(MESHPP:Apoptosis)"
                    }
                }
/functions:
  description: Retrieve the BEL function resource collection.
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
  get:
    headers:
      Accept:
        displayName: Accept
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
/functions/{fx}:
  description: Retrieve a BEL function resource.
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
  get:
    headers:
      Accept:
        displayName: Accept
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
/namespaces:
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
  /namespaces/{namespace}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/equivalents:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/orthologs:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/{value}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/equivalents/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/orthologs/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  # vim: ft=yaml sw=2 ts=2 sts=2 expandtab:

#%RAML 0.8
title: OpenBEL Platform
version: 0.0.2
baseUri: http://next.belframework.org/api
schemas:
  - annotation_resource:         !include http://next.belframework.org/schema/annotation_resource.schema.json
  - annotation_collection:       !include http://next.belframework.org/schema/annotation_collection.schema.json
  - annotation_value_resource:   !include http://next.belframework.org/schema/annotation_value_resource.schema.json
  - annotation_value_collection: !include http://next.belframework.org/schema/annotation_value_collection.schema.json
  - completion:                  !include http://next.belframework.org/schema/completion.schema.json
  - completion_collection:       !include http://next.belframework.org/schema/completion_collection.schema.json
  - evidence:                    !include http://next.belframework.org/schema/evidence.schema.json
  - evidence_resource:           !include http://next.belframework.org/schema/evidence_resource.schema.json
  - evidence_collection:         !include http://next.belframework.org/schema/evidence_collection.schema.json
  - match_result:                !include http://next.belframework.org/schema/match_result.schema.json
  - match_result_collection:     !include http://next.belframework.org/schema/match_result_collection.schema.json
traits:
  - ro_options:
      description: |
        Returns allowable HTTP methods for this <<name>>.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Allow:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'GET' ]
  - rw_options:
      description: |
        Returns allowable HTTP methods for this <<name>>.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Allow:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'GET', 'POST', 'PUT', 'DELETE' ]
  - create_options:
      description: |
        Returns allowable HTTP methods for this <<name>>.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Allow:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'GET', 'POST' ]
documentation:
  - title: Welcome
    content: |
      The OpenBEL Platform provides an Application Programming Interface (API) exposed over the Hypertext Transfer Protocol (HTTP). The primary goal of the API is to expose OpenBEL capabilities over the web to lower the technical barriers for users.
  - title: Functionality
    content: |
      The API provides the following:
      - Access and Search for BEL Annotations and Namespaces
      - Equivalence and Orthologize BEL expressions
      - Autocomplete syntax of BEL expressions
      - Access BEL Functions and Relationships
      - Store, query, and export BEL Evidence
  - title: Planned Functionality
    content: |
      We are currently working on the following:
      - Creating a group of BEL Evidence with returned resource "Location"
      - Support for [BEL version 2.0](http://wiki.openbel.org/display/BLVD)
      - Autocomplete with BEL expression semantics (e.g. namespace encoding, term signatures, etc.)
      - Creation of BEL knowledge networks from the Evidence collection
/api:
  description: |
    Root resource of the API. Lists all subresources contained within the API.
  options:
    is: [
      ro_options: { name: "root resource" }
    ]
  get:
    description: |
      Returns a list of linked *item* resources.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        body:
          application/hal+json:
            example: !include examples/root.example.json
/annotations:
  description: |
    Annotation collection within the API.

    This provides access to BEL annotation vocabularies such as MeSH, Gene Ontology, and Disease Ontology.

    BEL Evidence can be annotated to express knowledge about the evidence itself. Some important uses of annotations are:
      - Specify information about the biological system in which the facts represented by the statement hold or were demonstrated.
      - Specify information about the experimental methods used to demonstrate the facts.
      - Specify information about the knowledge source on which the statement is based, such as the citation and the specific text supporting the statement.
  options:
    is: [
      ro_options: { name: "annotation_collection" }
    ]
  get:
    description: |
      Returns the *annotation_collection* containing an array of all *annotation* resources.

      An *annotation* resource contains fields:
      - prefLabel: human-readable name
      - prefix:    short prefix
      - domain:    biological domain
      -

      The collection contains zero or more *annotation* resource objects. If the *annotation_collection* is empty then the result is an empty array.

    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

          **JSON Schema**
          - [annotation_collection](schemas/annotation_collection.schema.json)
          - [annotation](schemas/annotation_resource.schema.json)
        body:
          application/json:
            example: !include examples/annotation_collection.example.json
  /values:
    description: |
      Annotation Value collection for all Annotation resources within the API.

      This provides a collection of all BEL annotation values that can be listed and filtered.
    options:
      is: [
        ro_options: { name: "annotation_value_collection" }
      ]
    get:
      description: |
        Returns the *annotation_value_collection* across all *annotation* resources.

        Example: *Search by filter*

         **Limitations**

         This endpoint is limited to full-text searching including a *filter* like:
         ```json
         {
             "category": "fts",
             "name":     "search",
             "value":    "sarcoma"
         }
         ```

        **Complete Example**

        **GET http://next.belframework.org/api/annotations/values?filter={%22category%22:%22fts%22,%22name%22:%22search%22,%22value%22:%22sarcoma%22}&start=0&size=3**

        ```json
        {
          "annotation_value_collection": [
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "D012509",
                "name": "Sarcoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases/values/D012509"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases"
                  }
                }
              }
            },
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "1115",
                "name": "sarcoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology/values/1115"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology"
                  }
                }
              }
            },
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "D008223",
                "name": "Lymphoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases/values/D008223"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/mesh-diseases"
                  }
                }
              }
            }
          ]
        }
        ```

      queryParameters:
        start:
          type: integer
          description: |
            The annotation value resource to start from for paging purposes.
          example:  "0"
          required: false
        size:
          type: integer
          description: |
            The size of the annotation value resource collection to retrieve. This will return a slice of the annotation value resource collection relative to *start*.

            A size of zero or less will return all values.
          example:  3
          required: false
        filter:
          type: string
          description: |
            A filter to apply to the annotation value resource collection to narrow the resources retrieved.
          example: |
            {"category":"fts","name":"search","value":"sarcoma"}
          required: false
        faceted:
          type: string
          description: |
            The boolean indicator to provided faceted results for the annotation value resource collection. The default is to not facet.
          enum: [ 'true', 'yes', '1', 'on' ]
          example: no
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

            **JSON Schema**
            - [annotation_value_collection](schemas/annotation_value_collection.schema.json)
            - [annotation_value](schemas/annotation_value_resource.schema.json)
          body:
            application/json:
              example: !include examples/annotation_values_filter.example.json
        400:
          description: |
            [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1)

            Returned if a filter is malformed.
        404:
          description: |
            [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

            Returned if no annotation values were found for the FTS search.

            Returned if a `{"category":"fts", "name": "search", ...}` filter was not provided.
        501:
          description: |
            [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2)

            Returned if the client enabled the `faceted` query parameter. This is currently not implemented.
  /{annotation}:
    description: |
      Annotation resource identified by *{annotation}* URI parameter.
    uriParameters:
      annotation:
        type: string
        description: |
          An identifier string for an annotation. This is either the annotation prefix, name, or URI part.
        example: |
          "do" or "Disease Ontology" or "disease-ontology" (all resolve to the same annotation resource)
        required: true
    options:
      is: [
        ro_options: { name: "annotation resource" }
      ]
    get:
      description: |
        Returns the *annotation* resource identified by *{annotation}* URI parameter.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

            **JSON Schema**
            - [annotation](schemas/annotation_resource.schema.json)
          body:
            application/json:
              example: !include examples/annotation_resource.example.json
    /values:
      description: |
        Annotation Value collection within an Annotation resource identified by *{annotation}*.
      options:
        is: [
          ro_options: { name: "annotation_value_collection" }
        ]
      get:
        description: |
          Returns the *annotation_value_collection* across the *annotation* resource identified by *{annotation}* URI parameter.

          Example: *Search by filter*

           **Limitations**

           This endpoint is limited to full-text searching including a *filter* like:
           ```json
           {
               "category": "fts",
               "name":     "search",
               "value":    "sarcoma"
           }
           ```

          **Complete Example**

          **GET http://next.belframework.org/api/annotations/do/values?filter={%22category%22:%22fts%22,%22name%22:%22search%22,%22value%22:%22sarcoma%22}&start=0&size=3**

          ```json
          {
            "annotation_value_collection": [
              {
                "annotation_value": {
                  "type": "BiologicalProcessConcept",
                  "identifier": "1115",
                  "name": "sarcoma",
                  "_links": {
                    "self": {
                      "type": "annotation_value",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology/values/1115"
                    },
                    "collection": {
                      "type": "annotation",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology"
                    }
                  }
                }
              },
              {
                "annotation_value": {
                  "type": "BiologicalProcessConcept",
                  "identifier": "3071",
                  "name": "gliosarcoma",
                  "_links": {
                    "self": {
                      "type": "annotation_value",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology/values/3071"
                    },
                    "collection": {
                      "type": "annotation",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology"
                    }
                  }
                }
              },
              {
                "annotation_value": {
                  "type": "BiologicalProcessConcept",
                  "identifier": "3382",
                  "name": "liposarcoma",
                  "_links": {
                    "self": {
                      "type": "annotation_value",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology/values/3382"
                    },
                    "collection": {
                      "type": "annotation",
                      "href": "http://next.belframework.org/api/annotations/disease-ontology"
                    }
                  }
                }
              }
            ]
          }
          ```
        queryParameters:
          start:
            type: integer
            description: |
              The annotation value resource to start from for paging purposes.
            example:  "0"
            required: false
          size:
            type: integer
            description: |
              The size of the annotation value resource collection to retrieve. This will return a slice of the annotation value resource collection relative to *start*.

              A size of zero or less will return all values.
            example:  3
            required: false
          filter:
            type: string
            description: |
              A filter to apply to the annotation value resource collection to narrow the resources retrieved.
            example: |
              {"category":"fts","name":"search","value":"sarcoma"}
            required: false
          faceted:
            type: string
            description: |
              The boolean indicator to provided faceted results for the annotation value resource collection. The default is to not facet.
            enum: [ 'true', 'yes', '1', 'on' ]
            example: no
        responses:
          200:
            description: |
              [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

              **JSON Schema**
              - [annotation_value_collection](schemas/annotation_value_collection.schema.json)
            body:
              application/json:
                example: !include examples/annotation_value_collection.example.json
          400:
            description: |
              [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1)

              Returned if a filter is malformed.
          404:
            description: |
              [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

              Returned if no annotation values were found for the FTS search.

              Returned if a `{"category":"fts", "name": "search", ...}` filter was not provided.
          501:
            description: |
              [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2)

              Returned if the client enabled the `faceted` query parameter. This is currently not implemented.
      /{value}:
        description: |
          Annotation value resource identified by *{annotation}* and *{value}* URI parameters.
        options:
          is: [
            ro_options: { name: "annotation_value resource" }
          ]
        get:
          description: |
            Returns the *annotation_value* resource identified by *{annotation}* and *{value}* URI parameters.

            **Complete Example**

            **GET http://next.belframework.org/api/annotations/do/values/sarcoma**

            ```json
            {
              "annotation_value": {
                "type": "BiologicalProcessConcept",
                "identifier": "1115",
                "name": "sarcoma",
                "_links": {
                  "self": {
                    "type": "annotation_value",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology/values/1115"
                  },
                  "collection": {
                    "type": "annotation",
                    "href": "http://next.belframework.org/api/annotations/disease-ontology"
                  }
                }
              }
            }
            ```
          responses:
            200:
              description: |
                [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

                **JSON Schema**
                - [annotation_value](schemas/annotation_value_resource.schema.json)
              body:
                application/json:
                  example: !include examples/annotation_value_resource.example.json
            404:
              description: |
                [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

                Returned if a resource was not found by *{annotation}* and *{value}*.
/evidence:
  description: |
    Evidence collection within the API.

    This provides storage and query of Evidence resources.

    BEL Evidence represents a biological finding extracted from scientific literature. It is comprised of 5 parts:
      - Citation

        Identifies the reference (e.g. PubMed, Book, Journal, etc.) that contains supporting the *Summary Text*.

      - Summary Text

        The excerpt from the *Citation* that the *BEL Statement* is extracted from.

      - BEL Statement

        An expression that represents knowledge of the existence of biological entities and relationships between them that are known to be observed within a particular *Experiment Context*. The structure of a BEL Statement is explained further on the [OpenBEL Wiki](http://wiki.openbel.org/display/BLVD/Statements).

      - Experiment Context

        Data (Key/Value) that describes parameters of the experiment. For example an evidence observed in the lung of a human could include Uberon's *lung* concept (i.e. [uberon/UBERON:0002048](http://identifiers.org/uberon/UBERON:0002048)) and NCBI Taxonomy's *homo sapiens* concept (i.e. [taxonomy/9606](http://identifiers.org/taxonomy/9606)) respectively.

      - Metadata

        Data (Key/Value) about this evidence resource useful for bookkeeping or system integration purposes. For example one might want to capture a *Reviewer* and *Review Status* to track who is reviewing and this evidence's status respectively.

      - References

        States the vocabularies which the namespace and annotation values are drawn from. Each vocabulary should include a keyword and URI.

  options:
    is: [
      create_options: { name: "evidence collection" }
    ]
  post:
    description: |
      Creates one or more Evidence resource within the API.

      The following formats are supported:
      - Evidence JSON
        - media type:  `application/json`
        - JSON schema: [evidence.schema.json](http://next.belframework.org/schema/evidence.schema.json)
      - BEL Script
        - defined by [BEL Script V1.0 Format](http://wiki.openbel.org/display/BLDV20/BEL+Script+V1.0+Format)
        - media type: `application/bel`
      - XBEL (XML)
        - media type: `application/xml`
        - XML Schema: [xbel](http://resource.belframework.org/belframework/20150611/schema/xbel.xsd), [xbel-annotations](http://resource.belframework.org/belframework/20150611/schema/xbel-annotations.xsd)
      - [BEL JSON Graph Format](http://jsongraphformat.info/)
        - media type:  `application/vnd.jgf+json`
        - JSON schema: [bel-json-graph-2.0.schema.json](http://jsongraphformat.info/child-schemas/bel-json-graph-2.0.schema.json)
      - BEL RDF
        - defined within [bel.rb](https://github.com/OpenBEL/bel.rb) as a [format extension](https://github.com/OpenBEL/bel.rb/wiki/Format-Extensions). See [source](https://github.com/OpenBEL/bel.rb/tree/c1471942ce8326ad2399d66154c858d6a9fbcd6b/lib/bel/extensions/rdf)
        - media type
          - `application/n-quads`
          - `application/n-triples`
          - `application/rdf+xml`
          - `application/turtle`
          - `application/x-turtle`
          - `text/turtle`

      If you send a single Evidence JSON object then the resource's *Location* will be returned. However if you send multiple Evidence resources using any of the supported formats above then a *Location* will not be returned. This will be addressed in a future version.

    responses:
      201:
        description: |
          [201 Created](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2)

          The Evidence resource was created.

          The link to the evidence resource is conveyed is the *Link* header. This will only be set when a single Evidence resource is created.
      415:
        description: |
          [415 Unsupported Media Type](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16)

          The evidence resource body was not a supported media type..
    body:
      application/json:
        example: |
          {
            "evidence": {
              "bel_statement": "p(HGNC:MAPK1,pmod(P,T)) => kin(p(HGNC:MAPK1))",
              "citation": {
                "type": "PubMed",
                "name": "J Biol Chem. 1997 Jul 4;272(27):16917-23.",
                "id": "9202001"
              },
              "summary_text": "These kinases are regulated by the reversible dual\nphosphorylation of conserved threonine and tyrosine residues.",
              "experiment_context": [
                {
                  "name": "Species",
                  "value": "9606",
                  "uri": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno/9606",
                  "url": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"
                },
                {
                  "name": "CellLine",
                  "value": "U-937",
                  "uri": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno/U-937",
                  "url": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
                }
              ],
              "references": {
                "namespaces": {
                  "SFAM": "http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns",
                  "SCOMP": "http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns",
                  "HGNC": "http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns",
                  "CHEBI": "http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"
                },
                "annotations": {
                  "CellLine": {
                    "type": "url",
                    "domain": "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
                  },
                  "Species": {
                    "type": "url",
                    "domain": "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"
                  }
                }
              },
              "metadata": [
                {
                  "name": "document_header",
                  "value": {
                    "Name": "BEL Framework Example 1 Document",
                    "Description": "Example of modeling a full abstract taken from the BEL V1.0 Language Overview. ",
                    "Version": "20150611",
                    "Copyright": "Copyright (c) 2011-2015, Selventa. All Rights Reserved.",
                    "ContactInfo": "support@belframework.org",
                    "Authors": "Selventa",
                    "Licenses": "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License"
                  }
                }
              ]
            }
          }

      application/bel:
        example: |
          SET DOCUMENT Name = "BEL Framework Example 1 Document"
          SET DOCUMENT Description = "Example of modeling a full abstract taken from the BEL V1.0 Language Overview. "
          SET DOCUMENT Version = "20150611"
          SET DOCUMENT Copyright = "Copyright (c) 2011-2015, Selventa. All Rights Reserved."
          SET DOCUMENT ContactInfo = "support@belframework.org"
          SET DOCUMENT Authors = "Selventa"
          SET DOCUMENT Licenses = "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License"

          DEFINE NAMESPACE SFAM AS URL "http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns"
          DEFINE NAMESPACE SCOMP AS URL "http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns"
          DEFINE NAMESPACE HGNC AS URL "http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns"
          DEFINE NAMESPACE CHEBI AS URL "http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"

          DEFINE ANNOTATION CellLine AS URL "http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"
          DEFINE ANNOTATION Species AS URL "http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"

          SET Citation = {"PubMed","J Biol Chem. 1997 Jul 4;272(27):16917-23.","9202001"}
          SET Evidence = "These kinases are regulated by the reversible dual
          SET Species = "9606"
          SET CellLine = "U-937"
          p(HGNC:MAPK1,pmod(P,T)) => kin(p(HGNC:MAPK1))

      application/xml:
        example: |
          &lt?xml version="1.0"?&gt
          &ltbel:document xmlns:bel="http://belframework.org/schema/1.0/xbel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://belframework.org/schema/1.0/xbel http://resource.belframework.org/belframework/1.0/schema/xbel.xsd"&gt
            &ltbel:header&gt
              &ltbel:name&gtBEL Framework Example 1 Document&lt/bel:name&gt
              &ltbel:description&gtExample of modeling a full abstract taken from the BEL V1.0 Language Overview. &lt/bel:description&gt
              &ltbel:version&gt20150611&lt/bel:version&gt
              &ltbel:copyright&gtCopyright (c) 2011-2015, Selventa. All Rights Reserved.&lt/bel:copyright&gt
              &ltbel:contactInfo&gtsupport@belframework.org&lt/bel:contactInfo&gt
              &ltbel:authorGroup&gt
                &ltbel:author&gtSelventa&lt/bel:author&gt
              &lt/bel:authorGroup&gt
              &ltbel:licenseGroup&gt
                &ltbel:license&gtCreative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License&lt/bel:license&gt
              &lt/bel:licenseGroup&gt
            &lt/bel:header&gt
            &ltbel:namespaceGroup&gt
              &ltbel:namespace bel:prefix="SFAM" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/selventa-protein-families.belns"/&gt
              &ltbel:namespace bel:prefix="SCOMP" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/selventa-named-complexes.belns"/&gt
              &ltbel:namespace bel:prefix="HGNC" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/hgnc-human-genes.belns"/&gt
              &ltbel:namespace bel:prefix="CHEBI" bel:resourceLocation="http://resource.belframework.org/belframework/20150611/namespace/chebi.belns"/&gt
            &lt/bel:namespaceGroup&gt
            &ltbel:annotationDefinitionGroup&gt
              &ltbel:externalAnnotationDefinition bel:id="CellLine" bel:url="http://resource.belframework.org/belframework/20150611/annotation/cell-line.belanno"/&gt
              &ltbel:externalAnnotationDefinition bel:id="Species" bel:url="http://resource.belframework.org/belframework/20150611/annotation/species-taxonomy-id.belanno"/&gt
            &lt/bel:annotationDefinitionGroup&gt
            &ltbel:statementGroup&gt
              &ltbel:statement bel:relationship="=>"&gt
                &ltbel:annotationGroup&gt
                  &ltbel:citation bel:type="PubMed"&gt
                    &ltbel:reference&gt9202001&lt/bel:reference&gt
                    &ltbel:name&gtJ Biol Chem. 1997 Jul 4;272(27):16917-23.&lt/bel:name&gt
                  &lt/bel:citation&gt
                  &ltbel:evidence&gtThese kinases are regulated by the reversible dual
          phosphorylation of conserved threonine and tyrosine residues.&lt/bel:evidence&gt
                  &ltbel:annotation bel:refID="Species"&gt9606&lt/bel:annotation&gt
                  &ltbel:annotation bel:refID="CellLine"&gtU-937&lt/bel:annotation&gt
                &lt/bel:annotationGroup&gt
                &ltbel:subject&gt
                  &ltbel:term bel:function="proteinAbundance"&gt
                    &ltbel:parameter bel:ns="HGNC"&gtMAPK1&lt/bel:parameter&gt
                    &ltbel:term bel:function="proteinModification"&gt
                      &ltbel:parameter&gtP&lt/bel:parameter&gt
                      &ltbel:parameter&gtT&lt/bel:parameter&gt
                    &lt/bel:term&gt
                  &lt/bel:term&gt
                &lt/bel:subject&gt
                &ltbel:object&gt
                  &ltbel:term bel:function="kinaseActivity"&gt
                    &ltbel:term bel:function="proteinAbundance"&gt
                      &ltbel:parameter bel:ns="HGNC"&gtMAPK1&lt/bel:parameter&gt
                    &lt/bel:term&gt
                  &lt/bel:term&gt
                &lt/bel:object&gt
              &lt/bel:statement&gt
            &lt/bel:statementGroup&gt
          &lt/bel:document&gt

      application/vnd.jgf+json:
        example: |
          {
            "graph": {
              "type": "BEL-V1.0",
              "nodes": [
                {
                  "id": "p(HGNC:MAPK1,pmod(P,T))",
                  "label": "p(HGNC:MAPK1,pmod(P,T))"
                },
                {
                  "id": "kin(p(HGNC:MAPK1))",
                  "label": "kin(p(HGNC:MAPK1))"
                }
              ],
              "edges": [
                {
                  "source": "p(HGNC:MAPK1,pmod(P,T))",
                  "relation": "=>",
                  "target": "kin(p(HGNC:MAPK1))"
                }
              ]
            }
          }

      application/n-triples:
        example: |
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/ModifiedProteinAbundance&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1,pmod(P,T))" .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.openbel.org/vocabulary/hasModificationType&gt &lthttp://www.openbel.org/vocabulary/Phosphorylation&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt &lthttp://www.openbel.org/vocabulary/hasChild&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/ProteinAbundance&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1)" .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasConcept&gt &lthttp://www.openbel.org/bel/namespace/hgnc-human-genes/MAPK1&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/AbundanceActivity&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasActivityType&gt &lthttp://www.openbel.org/vocabulary/Kinase&gt .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "kin(p(HGNC:MAPK1))" .
          &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasChild&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Term&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/ProteinAbundance&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1)" .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasConcept&gt &lthttp://www.openbel.org/bel/namespace/hgnc-human-genes/MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasSubject&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasObject&gt &lthttp://www.openbel.org/bel/kin_p_HGNC_MAPK1&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasRelationship&gt &lthttp://www.openbel.org/vocabulary/DirectlyIncreases&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Statement&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.w3.org/2000/01/rdf-schema#label&gt "p(HGNC:MAPK1,pmod(P,T)) =&gt kin(p(HGNC:MAPK1))" .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt &lthttp://www.openbel.org/vocabulary/Evidence&gt .
          &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt &lthttp://www.openbel.org/vocabulary/hasEvidence&gt _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasStatement&gt &lthttp://www.openbel.org/bel/p_HGNC_MAPK1_pmod_P_T_DirectlyIncreases_kin_p_HGNC_MAPK1&gt .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasCitation&gt &lthttp://bio2rdf.org/pubmed:9202001&gt .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasEvidenceText&gt "These kinases are regulated by the reversible dual\nphosphorylation of conserved threonine and tyrosine residues." .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasAnnotation&gt &lthttp://www.openbel.org/bel/annotation/species-taxonomy-id/9606&gt .
          _:1ddf16d0-4a7b-0133-5cfc-082e5f8a66ae &lthttp://www.openbel.org/vocabulary/hasAnnotation&gt &lthttp://www.openbel.org/bel/annotation/cell-line/U-937&gt .

  get:
    description: |
      Retrieve the evidence resource collection.

      All evidence resources will be returned by default.

      The collection can be returned page by page by providing a *start* (defaults to `0`) index and *size* (defaults to no size limit) to return.

      This collection can be filtered by providing one or more *filter* options. A filter specifies the *category*, *name*, and *value* of the filter and is encoded as a JSON object. For example an evidence metadata filter might be encoded as:

      ```json
        {
          "category": "metadata",
          "name": "status",
          "value": "Approved"
        }
      ```

      This collection can be filtered using by a full-text search filter such as:

      ```json
        {
          "category": "fts",
          "name": "search",
          "value": "lung liver pancreas"
        }
      ```

      ```json
        {
          "category": "fts",
          "name": "search",
          "value": "\"subdural hematoma\""
        }
      ```

      This collection can specify the *faceted* boolean option. Facets will reflect all (possibly filtered) evidence resources irrespective of *start* and *size* paging.

      Facts are an array of facet objects that are composed of a *filter* and *count*. For example for the evidence metadata filter the facet object would be encoded as:

      ```json
        {
          "category": "metadata",
          "name": "Status",
          "values": [
            {
              "value": "Approved",
              "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Approved\"}",
              "count": 10200
            }
          ]
        },
      ```

      The *filter* property value can be used as a *filter* option. This is intended to support filtering the evidence resource collection by selected facets.

      The *max_values_per_facet* option can be specified to limit the number of returned facet values by category, name pairs. For example, setting *max_values_per_facet* to `2` would return up to 2 distinct facets values for `{ "category": "citation", "name": "id", ... }`.
    headers:
      Accept:
        displayName: Accept
        description: |
          The Accept header informs the server which media types the client accepts.
    queryParameters:
      start:
        type: integer
        description: |
          The evidence resource to start from for paging purposes.

          The default value is `0`. This value will return evidence resources starting from the beginning of collection.
        example: 100
        required: false
      size:
        type: integer
        description: |
          The size of the evidence resource collection to retrieve. This will return a slice of the evidence resource collection relative to *start*.

          The default is `0`. This value will return all evidence resources in the collection.
        example: 100
        required: false
      filter:
        type: string
        description: |
          A filter to apply to the evidence resource collection to narrow the resources retrieved.

          The default is to not apply filters. If filters are not specified then all evidence resources, in the collection, will be returned.
        example: |
          {"category":"experiment_context","name":"Anatomy","value":"prostate gland"}
          {"category":"fts","name":"search","value":"\"subdural hematoma\" carcinoma"}
          {"category":"fts","name":"search","value":"homatoma -carcinoma"}
        required: false
      faceted:
        type: string
        description: |
          The boolean indicator to provided faceted results for the evidence resource collection.

          The default is `false`. This value will not return facets in the response.
        enum: [ 'true', 'yes', '1', 'on' ]
        example: yes
      max_values_per_facet:
        type: integer
        description: e|
          The maximum about of facet values to display for every category, name pair.

          The default is `0`. This value will return all facet values (i.e. unbounded) for every category, name pair.
        example: 20
        required: false
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)

          An example request for this resource might be:

          - Path: `/api/evidence`
          - Query parameters:
            - `start=0`
            - `size=1`
            - `faceted=yes`
            - `max_values_per_facet=1`
            - `filter`
            ```json
            {
              "category":"experiment_context",
              "name":"Anatomy",
              "value":"prostate gland"
            }
            ```

          Example URL: [http://next.belframework.org/api/evidence?start=0&size=1&faceted=yes&max_values_per_facet=1&filter={"category":"experiment_context","name":"Anatomy","value":"prostate gland"}](http://next.belframework.org/api/evidence?start=0&size=1&faceted=yes&max_values_per_facet=1&filter={%22category%22:%22experiment_context%22,%22name%22:%22Anatomy%22,%22value%22:%22prostate gland%22})

          **JSON Schema**
          - [evidence_collection](schemas/evidence_collection.schema.json)
          - [evidence_resource](schemas/evidence_resource.schema.json)
          - [evidence](schemas/evidence.schema.json)

        body:
          application/json:
            example: |
              {
                "evidence_collection": [
                  {
                    "evidence": {
                      "bel_statement": "a(CHEBI:\"1-octadec-9-enoylglycero-3-phosphate\") increases kin(p(HGNC:EGFR))",
                      "citation": {
                        "type": "PubMed",
                        "name": "Exp Cell Res 2003 Mar 10 284(1) 99-110",
                        "id": "12648469",
                        "date": "",
                        "authors": [],
                        "comment": ""
                      },
                      "summary_text": "Treatment of cells with GPCR agonists such as endothelin- 1 (ET-1), thrombin, bombesin, and lysophosphatidic acid (LPA) transactivates ErbB1 (reviewed by Zwick et al. [48]). Mechanistically, the process involves rapid stimulation of metalloproteinases followed by cleavage of an ErbB1 ligand precursor, e.g., pro-HB-EGF [49], whose binding activates ErbB1 and downstream signaling pathways",
                      "experiment_context": [
                        {
                          "name": "Species",
                          "value": "9606"
                        },
                        {
                          "name": "Anatomy",
                          "value": "prostate gland"
                        },
                        {
                          "name": "Cell",
                          "value": "squamous epithelial cell"
                        }
                      ],
                      "metadata": [
                        {
                          "name": "document_header",
                          "value": {
                            "Name": "BEL Framework Large Corpus Document",
                            "Description": "Approximately 61,000 statements.",
                            "Version": "20150611",
                            "Copyright": "Copyright (c) 2011-2015, Selventa. All rights reserved.",
                            "Authors": "Selventa",
                            "Licenses": "Creative Commons Attribution-Non-Commercial-ShareAlike 3.0 Unported License",
                            "ContactInfo": "support@belframework.org"
                          }
                        }
                      ]
                    },
                    "_links": {
                      "self": {
                        "type": "evidence",
                        "href": "http://next.belframework.org/api/evidence/56015a638a4cca1317005637"
                      },
                      "collection": {
                        "type": "evidence_collection",
                        "href": "http://next.belframework.org/api/evidence"
                      }
                    }
                  }
                ],
                "facets": [
                  {
                    "category": "metadata",
                    "name": "document_header",
                    "values": [
                      {
                        "value": [
                          "Authors",
                          "Selventa"
                        ],
                        "filter": "{\"category\":\"metadata\",\"name\":\"document_header\",\"value\":[\"Authors\",\"Selventa\"]}",
                        "count": 423
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Anatomy",
                    "values": [
                      {
                        "value": "prostate gland",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}",
                        "count": 423
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Species",
                    "values": [
                      {
                        "value": "9606",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Species\",\"value\":\"9606\"}",
                        "count": 263
                      }
                    ]
                  },
                  {
                    "category": "citation",
                    "name": "id",
                    "values": [
                      {
                        "value": "12351634",
                        "filter": "{\"category\":\"citation\",\"name\":\"id\",\"value\":\"12351634\"}",
                        "count": 62
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Cell",
                    "values": [
                      {
                        "value": "fibroblast",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Cell\",\"value\":\"fibroblast\"}",
                        "count": 20
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Cellline",
                    "values": [
                      {
                        "value": "LNCAP cell",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Cellline\",\"value\":\"LNCAP cell\"}",
                        "count": 17
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Disease",
                    "values": [
                      {
                        "value": "prostate carcinoma in situ",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Disease\",\"value\":\"prostate carcinoma in situ\"}",
                        "count": 13
                      }
                    ]
                  },
                  {
                    "category": "experiment_context",
                    "name": "Cellstructure",
                    "values": [
                      {
                        "value": "Cytoplasm",
                        "filter": "{\"category\":\"experiment_context\",\"name\":\"Cellstructure\",\"value\":\"Cytoplasm\"}",
                        "count": 4
                      }
                    ]
                  }
                ],
                "metadata": {
                  "collection_paging": {
                    "total": 52399,
                    "total_filtered": 423,
                    "total_pages": 423,
                    "current_page": 1,
                    "current_page_size": 1
                  }
                },
                "_links": {
                  "self": {
                    "type": "evidence_collection",
                    "href": "http://next.belframework.org/api/evidence?start=0&size=1&filter={\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}"
                  },
                  "start": {
                    "type": "evidence_collection",
                    "href": "http://next.belframework.org/api/evidence?start=0&size=1&filter={\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}"
                  },
                  "next": {
                    "type": "evidence_collection",
                    "href": "http://next.belframework.org/api/evidence?start=1&size=1&filter={\"category\":\"experiment_context\",\"name\":\"Anatomy\",\"value\":\"prostate gland\"}"
                  }
                }
              }
      404:
        description: |
          [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

          The evidence collection could not be found given your request. This typically indicates an empty evidence collection for the provided query parameters.
      406:
        description: |
          [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7)

          The evidence collection identified cannot be returned in the client-specified Content Type.
  /{identifier}:
    description:
    options:
      is: [
        rw_options: { name: "evidence resource" }
      ]
    get:
    put:
      description: |
        Replaces an evidence resource identified by *{identifier}*.

        Include a *profile* parameter in the *Content-Type* header to convey the schema evidence schema for the JSON document.

        *Example*:

        - `Content-Type: application/json; profile=http://next.belframework.org/schema/evidence_resource.schema.json`
      body:
        application/json:
          schema: evidence_resource
          example: |
            {
              "evidence": {
                "bel_statement": "a(CHEBI:\"reactive oxygen species\") increases r(HGNC:JUN)",
                "citation": {
                  "type": "PubMed",
                  "name": "Free Radic Biol Med 2000 Feb 1 28(3) 463-99",
                  "id": "10699758"
                },
                "experiment_context": {
                  "Species": "9606",
                  "CellLine": "LNCAP cell",
                  "Anatomy": "prostate gland",
                  "Cell": "fibroblast",
                  "Disease": "leukemia"
                },
                "metadata": {
                  "status": "Approved"
                }
              }
            }
      responses:
        202:
          description: |
            [202 Accepted](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3)

            The replacement for the evidence resource will be applied.
        404:
          description: |
            [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5)

            An evidence resource, identified by *{identifier}*, does not exist.
        415:
          description: |
            [415 Unsupported Media Type](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16)

            The evidence resource body was not a supported media type.
    patch:
    delete:
/expressions:
  /{bel}/completions:
    description: |
      Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

      Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

      Custom Caret Position:

      The caret position can be provided to indicate where to complete from.

      Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
    uriParameters:
      bel:
        type: string
        description: BEL statement fragment; Completions will be provided for this input.
        required: false
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    get:
      description: |
        Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

        Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

        Custom Caret Position:

        The caret position can be provided to indicate where to complete from.

        Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
      headers:
        Accept:
          displayName: Accept
      queryParameters:
        caret_position:
          type: integer
          description: The position of the caret within the *bel* input. Defaults to the right-most caret_position for *bel* (e.g. length of *bel* input).
          example: 0
          required: false
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          body:
            application/json:
              example: |
                {
                  "completions": [
                    {
                      "type": "namespace_prefix",
                      "label": "HGNC",
                      "value": "HGNC:",
                      "highlight": {
                        "start_position": 2,
                        "end_position": 3,
                        "range_type": "inclusive"
                      },
                      "actions": [
                        {
                          "delete": {
                              "start_position": 2,
                              "end_position": 3,
                              "range_type": "inclusive"
                          },
                          "insert": {
                              "position": 2,
                              "value": "HGNC:"
                          },
                          "move_cursor": {
                              "position": 7
                          }
                        }
                      ]
                    }
                  ]
                }
              schema: completion_collection
  /{bel}/components:
    description: |
      Retrieve the components of a *BEL* expression fragment. Currently this will only return the *subject*, *relationship*, and *object* understood from BEL statement expression.
    uriParameters:
      bel:
        type: string
        description: BEL statement expression to recognize; Components will be returned for this input.
        required: false
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    get:
      description: |
        Retrieve the components of a *BEL* expression fragment. Currently this will only return the *subject*, *relationship*, and *object* understood from BEL statement expression.

        Examples:

          - *p(HGNC:AKT1)* yields:

            ```json
            {
                "expression_components": {
                    "subject":      "p(HGNC:AKT1)",
                    "relationship": null,
                    "object":       null
                }
            }
            ```

          - *p(HGNC:AKT1) -> bp(MESHPP:Apoptosis)* yields:

            ```json
            {
                "expression_components": {
                    "subject":      "p(HGNC:AKT1)",
                    "relationship": "increases",
                    "object":       "bp(MESHPP:Apoptosis)"
                }
            }
            ```

          - *a(CHEBI:"phosphatidyl-L-serine") increases pep(p(HGNC:F3))* yields:

            ```json
            {
                "expression_components": {
                    "subject":      "a(CHEBI:\"phosphatidyl-L-serine\")",
                    "relationship": "increases",
                    "object":       "pep(p(HGNC:F3))"
                }
            }
            ```

      queryParameters:
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          body:
            application/json:
              example: |
                {
                    "expression_components": {
                        "subject":      "p(HGNC:AKT1)",
                        "relationship": "increases",
                        "object":       "bp(MESHPP:Apoptosis)"
                    }
                }
/functions:
  description: Retrieve the BEL function resource collection.
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
  get:
    headers:
      Accept:
        displayName: Accept
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
/functions/{fx}:
  description: Retrieve a BEL function resource.
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
  get:
    headers:
      Accept:
        displayName: Accept
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
/namespaces:
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        description: |
          [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
  /namespaces/{namespace}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/equivalents:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/orthologs:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/{value}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/equivalents/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/orthologs/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          description: |
            [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  # vim: ft=yaml sw=2 ts=2 sts=2 expandtab: