Towards #51: Add the PUT to RAML. Also, update POST response

#%RAML 0.8
title: Okapi Core API
version: 0.1
baseUri: https://okapi.io
## mediaType:  application/json
schemas:
  - ModuleDescriptor: !include ModuleDescriptor.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModules: !include TenantModules.json

#resourceTypes:
#traits:

# The following are a set of APIs that module web service must accept/consume
# to allow okapi environment to orchestrate it
#
# This version assumes that a module instance may be shared by multiple
# tenants, e.g we have a global set of module instances

# TODO we will most likely need a web service to list and browse module types

/_/modules:
  post:
    description: Creates an instance of a given module type, includes all
      necessary mechanics to put the module into operation (launching
      a process, binding to a port, setting up routing)
     # most likely we will want to read some initial configuration
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        headers:
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
  /{module_id}:
    get:
      description: Retrieve information about the module instance
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update the module instance.
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    delete:
      description: Remove module instance from operation
        (shutdown process etc)
      responses:
        204:

/_/tenants:
  post:
    description: create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: tenant has been created
        headers:
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor

  /{tenant_id}:
    get:
      description: retrieve tenant
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
    put:
      description: update tenant
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
    delete:
      description: remove tenant

    /modules:
      get:
        description: Map of module instances accessible by the tenant
        responses:
          200:
            body:
              application/json:
                schema: TenantModules
      post:
        description: Link a module instance to the specified tenant
        body:
          application/json:
            schema: TenantModuleDescriptor

      /{module_tenant_id}:
        get:
          description: look up tenant-module mapping
          responses:
            200:
              body:
                application/json:
                  schema: TenantModuleDescriptor
        delete:
          description: remove tenant-module registration

/_/health:
  get:
    description: health status
    responses:
      200:
        description: guess what

#%RAML 0.8
title: Okapi Core API
version: 0.1
baseUri: https://okapi.io
## mediaType:  application/json
schemas:
  - ModuleDescriptor: !include ModuleDescriptor.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModules: !include TenantModules.json

#resourceTypes:
#traits:

# The following are a set of APIs that module web service must accept/consume
# to allow okapi environment to orchestrate it
#
# This version assumes that a module instance may be shared by multiple
# tenants, e.g we have a global set of module instances

# TODO we will most likely need a web service to list and browse module types

/_/modules:
  post:
    description: Creates an instance of a given module type, includes all
      necessary mechanics to put the module into operation (launching
      a process, binding to a port, setting up routing)
     # most likely we will want to read some initial configuration
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        headers:
          Location:
            description: URI to the created module instance
  /{module_id}:
    get:
      description: Retrieve information about the module instance
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    delete:
      description: Remove module instance from operation
        (shutdown process etc)
      responses:
        204:

/_/tenants:
  post:
    description: create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: tenant has been created
        headers:
          Location:
            description: URI to the created tenant

  /{tenant_id}:
    get:
      description: retrieve tenant
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
    delete:
      description: remove tenant

    /modules:
      get:
        description: Map of module instances accessible by the tenant
        responses:
          200:
            body:
              application/json:
                schema: TenantModules
      post:
        description: Link a module instance to the specified tenant
        body:
          application/json:
            schema: TenantModuleDescriptor

      /{module_tenant_id}:
        get:
          description: look up tenant-module mapping
          responses:
            200:
              body:
                application/json:
                  schema: TenantModuleDescriptor
        delete:
          description: remove tenant-module registration

/_/health:
  get:
    description: health status
    responses:
      200:
        description: guess what


document OPTIONS requests; refs #24

document OPTIONS requests; refs #24

#%RAML 0.8
title: OpenBEL API
version: 0.0.2
baseUri: http://next.belframework.org
schemas:
  - completion_collection: !include http://next.belframework.org/schema/completion_collection.schema.json
  - evidence_collection:   !include http://next.belframework.org/schema/evidence_collection.schema.json
  - evidence:              !include http://next.belframework.org/schema/evidence.schema.json
/api:
  description: The root resource collection.
  options:
    description: Returns allowable HTTP methods.
    responses:
      200:
        headers:
          Accept:
            description: Allowable HTTP methods.
            type:        string
            enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
  get:
    headers:
        Accept:
          displayName: Accept
    responses:
      200:
        body:
          application/hal+json:
            example: |
              {
                "_links": {
                  "item": [
                    {
                      "href": "http://next.belframework.org/api/evidence"
                    },
                    {
                      "href": "http://next.belframework.org/api/expressions"
                    },
                    {
                      "href": "http://next.belframework.org/api/functions"
                    },
                    {
                      "href": "http://next.belframework.org/api/namespaces"
                    }
                  ]
                }
              }
  /annotations:
    description: Represents the annotation resource collection.
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    get:
      description: Retrieves all annotation resources.
    /{annotation}:
      description: Represents a single annotation resource.
      options:
        description: Returns allowable HTTP methods.
        responses:
          200:
            headers:
              Accept:
                description: Allowable HTTP methods.
                type:        string
                enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
      get:
        description: Retrieves an annotation resource.
      /{annotation}/values:
        description: Represents all annotation value resources available on the annotation resource identified by *{annotation}*.
        options:
          description: Returns allowable HTTP methods.
          responses:
            200:
              headers:
                Accept:
                  description: Allowable HTTP methods.
                  type:        string
                  enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
        /{value}:
          description: Represents a single annotation value resources available on the annotation resource identified by *{annotation}* and *{value}*.
          options:
            description: Returns allowable HTTP methods.
            responses:
              200:
                headers:
                  Accept:
                    description: Allowable HTTP methods.
                    type:        string
                    enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
          get:
            description:
  /evidence:
    description: |
      Operate on the evidence resource collection.

      *Operations*

      - Filter the evidence resource collection using `GET /evidence` with query parameters.
      - Retrieve an evidence resource using `GET /evidence/{id}`.
      - Create a new evidence resource using `POST /evidence` with a supported content type.
      - Update an existing evidence resource using `PUT /evidence/{id}` with a supported content type.
      - Delete an existing evidence resource using `DELETE /evidence/{id}`.

    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    post:
      description: |
        Create an evidence resource.

        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.schema.json`
      responses:
        201:
          description: |
            *201 Created*

            The evidence resource was created.

            The link to the evidence resource is conveyed is the *Link* header.
        415:
          description: |
            *415 Unsupported Media Type*

            The evidence resource body was not a supported media type..
      body:
        application/json:
          schema: evidence
          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"
                },
                "biological_context": {
                  "Species": "9606",
                  "CellLine": "LNCAP cell",
                  "Anatomy": "prostate gland",
                  "Cell": "fibroblast",
                  "Disease": "leukemia"
                },
                "metadata": {
                  "status": "Approved"
                }
              }
            }
    get:
      description: |
        Retrieve the evidence resource collection.

        This collection must be paged using *offset* (defaults to `0`) as the start index and *length* (defaults to `100`) as the number of evidence resources to return.

        This collection can be filtered by specifying one or more *filter* query parameters. A filter query parameter specifies the *category*, *name*, and *value* of the filter and is encoded as a JSON object. For example the citation id filter might be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101"
          }
        ```

        This collection includes a *facets* array where each facet value is captured individually. For example for the citation id filter the facet object would be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101",
            "filter": "{\"category\": \"citation\", \"name\": \"id\", \"value\": \"133785101\"}",
            "count": 25
          }
        ```

        The *filter* property value has the same form as the *filter* query parameter. This is intended to support filtering the evidence resource collection by selected facets.
      headers:
        Accept:
          displayName: Accept
          description: |
            The Accept header informs the server which media types the client accepts.
      queryParameters:
        offset:
          type: integer
          description: The evidence resource index that starts a page of the evidence resource collection.
          example: 0
          required: false
        length:
          type: integer
          description: The length of the evidence resource collection to retrieve.
          example: 100
          required: false
        filter:
          type: string
          description: A filter to apply to the evidence resource collection to narrow the resources retrieved.
          example: |
            {"category":"context","name":"Anatomy","value":"prostate gland"}
          required: false
      responses:
        200:
          description: |
            An example path for this resource might be `http://next.belframework.org/api/evidence?offset=0&length=1&filter={%22category%22:%22context%22,%22name%22:%22Anatomy%22,%22value%22:%22prostate%20gland%22}`.
          body:
            application/json:
              schema: evidence_collection
              example: |
                {
                  "evidence": [
                    {
                      "bel_statement": "p(HGNC:CDH1) decreases cat(complex(p(HGNC:ITGAV),p(HGNC:ITGB5)))",
                      "citation": {
                        "type": "Other",
                        "name": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer",
                        "id": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer"
                      },
                      "biological_context": {
                        "Species": "9606"
                      },
                      "metadata": {
                        "status": "Review"
                      }
                    }
                  ]
                  "facets": [
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "9606",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"9606\"}",
                      "count": 49071
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10090",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10090\"}",
                      "count": 19416
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Review",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Review\"}",
                      "count": 18954
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Approved",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Approved\"}",
                      "count": 18947
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Rejected",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Rejected\"}",
                      "count": 18896
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Draft",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Draft\"}",
                      "count": 18784
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10116",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10116\"}",
                      "count": 7091
                    },
                    {
                      "category": "context",
                      "name": "Anatomy",
                      "value": "liver",
                      "filter": "{\"category\":\"context\",\"name\":\"Anatomy\",\"value\":\"liver\"}",
                      "count": 2357
                    }
                  ]
                }
    /{identifier}:
      description:
      options:
        description: Returns allowable HTTP methods.
        responses:
          200:
            headers:
              Accept:
                description: Allowable HTTP methods.
                type:        string
                enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
      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.schema.json`
        body:
          application/json:
            schema: evidence
            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"
                    },
                    "biological_context": {
                      "Species": "9606",
                      "CellLine": "LNCAP cell",
                      "Anatomy": "prostate gland",
                      "Cell": "fibroblast",
                      "Disease": "leukemia"
                    },
                    "metadata": {
                      "status": "Approved"
                    }
                  }
                ]
              }
        responses:
          202:
            description: |
              *202 Accepted*

              The replacement for the evidence resource will be applied.
          404:
            description: |
              *404 Not Found*

              An evidence resource, identified by *{identifier}*, does not exist.
          415:
            description: |
              *415 Unsupported Media Type*

              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:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    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:
          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
  /functions:
    description: Retrieve the BEL function resource collection.
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /functions/{fx}:
    description: Retrieve a BEL function resource.
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /namespaces:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
  /namespaces/{namespace}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
  /namespaces/{namespace}/equivalents:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    post:
  /namespaces/{namespace}/orthologs:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
    post:
  /namespaces/{namespace}/{value}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
  /namespaces/{namespace}/{value}/equivalents/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
  /namespaces/{namespace}/{value}/orthologs/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
              enum:        [ 'OPTIONS', 'POST', 'GET', 'PUT', 'DELETE' ]
# vim: ft=yaml sw=2 ts=2 sts=2 expandtab:

#%RAML 0.8
title: OpenBEL API
version: 0.0.2
baseUri: http://next.belframework.org
schemas:
  - completion_collection: !include http://next.belframework.org/schema/completion_collection.schema.json
  - evidence_collection:   !include http://next.belframework.org/schema/evidence_collection.schema.json
  - evidence:              !include http://next.belframework.org/schema/evidence.schema.json
/api:
  description: The root resource collection.
  get:
    headers:
        Accept:
          displayName: Accept
    responses:
      200:
        body:
          application/hal+json:
            example: |
              {
                "_links": {
                  "item": [
                    {
                      "href": "http://next.belframework.org/api/evidence"
                    },
                    {
                      "href": "http://next.belframework.org/api/expressions"
                    },
                    {
                      "href": "http://next.belframework.org/api/functions"
                    },
                    {
                      "href": "http://next.belframework.org/api/namespaces"
                    }
                  ]
                }
              }
  /annotations:
    description: Represents the annotation resource collection.
    get:
      description: Retrieves all annotation resources.
    /{annotation}:
      description: Represents a single annotation resource.
      get:
        description: Retrieves an annotation resource.
      /{annotation}/values:
        description: Represents all annotation value resources available on the annotation resource identified by *{annotation}*.
        /{value}:
          description: Represents a single annotation value resources available on the annotation resource identified by *{annotation}* and *{value}*.
          get:
            description:
  /evidence:
    description: |
      Operate on the evidence resource collection.

      *Operations*

      - Filter the evidence resource collection using `GET /evidence` with query parameters.
      - Retrieve an evidence resource using `GET /evidence/{id}`.
      - Create a new evidence resource using `POST /evidence` with a supported content type.
      - Update an existing evidence resource using `PUT /evidence/{id}` with a supported content type.
      - Delete an existing evidence resource using `DELETE /evidence/{id}`.

    post:
      description: |
        Create an evidence resource.

        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.schema.json`
      responses:
        201:
          description: |
            *201 Created*

            The evidence resource was created.

            The link to the evidence resource is conveyed is the *Link* header.
        415:
          description: |
            *415 Unsupported Media Type*

            The evidence resource body was not a supported media type..
      body:
        application/json:
          schema: evidence
          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"
                },
                "biological_context": {
                  "Species": "9606",
                  "CellLine": "LNCAP cell",
                  "Anatomy": "prostate gland",
                  "Cell": "fibroblast",
                  "Disease": "leukemia"
                },
                "metadata": {
                  "status": "Approved"
                }
              }
            }
    get:
      description: |
        Retrieve the evidence resource collection.

        This collection must be paged using *offset* (defaults to `0`) as the start index and *length* (defaults to `100`) as the number of evidence resources to return.

        This collection can be filtered by specifying one or more *filter* query parameters. A filter query parameter specifies the *category*, *name*, and *value* of the filter and is encoded as a JSON object. For example the citation id filter might be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101"
          }
        ```

        This collection includes a *facets* array where each facet value is captured individually. For example for the citation id filter the facet object would be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101",
            "filter": "{\"category\": \"citation\", \"name\": \"id\", \"value\": \"133785101\"}",
            "count": 25
          }
        ```

        The *filter* property value has the same form as the *filter* query parameter. This is intended to support filtering the evidence resource collection by selected facets.
      headers:
        Accept:
          displayName: Accept
          description: |
            The Accept header informs the server which media types the client accepts.
      queryParameters:
        offset:
          type: integer
          description: The evidence resource index that starts a page of the evidence resource collection.
          example: 0
          required: false
        length:
          type: integer
          description: The length of the evidence resource collection to retrieve.
          example: 100
          required: false
        filter:
          type: string
          description: A filter to apply to the evidence resource collection to narrow the resources retrieved.
          example: |
            {"category":"context","name":"Anatomy","value":"prostate gland"}
          required: false
      responses:
        200:
          description: |
            An example path for this resource might be `http://next.belframework.org/api/evidence?offset=0&length=1&filter={%22category%22:%22context%22,%22name%22:%22Anatomy%22,%22value%22:%22prostate%20gland%22}`.
          body:
            application/json:
              schema: evidence_collection
              example: |
                {
                  "evidence": [
                    {
                      "bel_statement": "p(HGNC:CDH1) decreases cat(complex(p(HGNC:ITGAV),p(HGNC:ITGB5)))",
                      "citation": {
                        "type": "Other",
                        "name": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer",
                        "id": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer"
                      },
                      "biological_context": {
                        "Species": "9606"
                      },
                      "metadata": {
                        "status": "Review"
                      }
                    }
                  ]
                  "facets": [
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "9606",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"9606\"}",
                      "count": 49071
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10090",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10090\"}",
                      "count": 19416
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Review",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Review\"}",
                      "count": 18954
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Approved",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Approved\"}",
                      "count": 18947
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Rejected",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Rejected\"}",
                      "count": 18896
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Draft",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Draft\"}",
                      "count": 18784
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10116",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10116\"}",
                      "count": 7091
                    },
                    {
                      "category": "context",
                      "name": "Anatomy",
                      "value": "liver",
                      "filter": "{\"category\":\"context\",\"name\":\"Anatomy\",\"value\":\"liver\"}",
                      "count": 2357
                    }
                  ]
                }
    /{identifier}:
      description:
      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.schema.json`
        body:
          application/json:
            schema: evidence
            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"
                    },
                    "biological_context": {
                      "Species": "9606",
                      "CellLine": "LNCAP cell",
                      "Anatomy": "prostate gland",
                      "Cell": "fibroblast",
                      "Disease": "leukemia"
                    },
                    "metadata": {
                      "status": "Approved"
                    }
                  }
                ]
              }
        responses:
          202:
            description: |
              *202 Accepted*

              The replacement for the evidence resource will be applied.
          404:
            description: |
              *404 Not Found*

              An evidence resource, identified by *{identifier}*, does not exist.
          415:
            description: |
              *415 Unsupported Media Type*

              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
    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:
          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
  /functions:
    description: Retrieve the BEL function resource collection.
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /functions/{fx}:
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /namespaces:
  /namespaces/{namespace}:

  /namespaces/{namespace}/equivalents:
    post:
  /namespaces/{namespace}/orthologs:
    post:
  /namespaces/{namespace}/{value}:
  /namespaces/{namespace}/{value}/equivalents/namespaces/{target}:
  /namespaces/{namespace}/{value}/orthologs/namespaces/{target}:
# vim: ft=yaml sw=2 ts=2 sts=2 expandtab:


Suggested API doc change to fix #581

Suggested API doc change to fix #581

#%RAML 0.8
---
title: WireMock
version: 2.3.2
mediaType: application/json

documentation:
  - title: WireMock admin
    content: |
       The WireMock admin API.

schemas:
  - stubMapping: !include schemas/stub-mapping.schema.json
  - stubMappings: !include schemas/stub-mappings.schema.json
  - requestPattern: !include schemas/request-pattern.schema.json

/__admin/mappings:
  description: Stub mappings

  get:
    description: Get all stub mappings

    queryParameters:
      limit:
        displayName: Query limit
        type: number
        description: The maximum number of results to return
        example: 10
        required: false
      offset:
        displayName: Query offset
        type: number
        description: The start index of the results to return
        example: 25
        required: false

    responses:
      200:
        description: All stub mappings
        body:
          application/json:
            schema: stubMappings
            example: !include examples/stub-mappings.example.json

  post:
    description: Create a new stub mapping
    body:
      application/json:
        example: !include examples/stub-mapping-no-id.example.json
        schema: stubMapping

    responses:
      201:
        description: Successfully created
        body:
          application/json:
            example: !include examples/stub-mapping-with-id.example.json
            schema: stubMapping

  delete:
    description: Delete all stub mappings
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /reset:
      description: Stub mappings
      post:
        description: Reset stub mappings (restore to defaults defined back the backing store)
        responses:
          200:
            description: Successfully reset

  /{stubMappingId}:
    description: Single stub mapping
    get:
      description: Get a single stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/stub-mapping-with-id.example.json
              schema: stubMapping

    uriParameters:
      stubMappingId:
        required: true
        example: 730d3e32-d098-4169-a20c-554c3bedce58
        displayName: Stub mapping ID
        description: The UUID of stub mapping

    put:
      description: Update an existing stub mapping
      body:
        application/json:
          example: !include examples/stub-mapping-no-id.example.json
          schema: stubMapping

      responses:
        200:
          body:
            application/json:
              schema: stubMapping
              example: !include examples/stub-mapping-with-id.example.json

    delete:
      description: Delete a stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/empty.example.json

  /save:
    description: Stub mappings
    post:
      description: Save all persistent stub mappings to the backing store
      responses:
        200:
          description: Successfully removed

/__admin/scenarios:
  description: Scenarios support modelling of stateful behaviour

  /reset:
    description: Scenarios
    post:
      description: Reset the state of all scenarios
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

/__admin/requests:
  description: Logged requests and responses received by the mock service

  get:
    description: Get received requests
    queryParameters:
      limit:
        displayName: Query limit
        description: The maximum number of results to return
        example: 10
      since:
        example: 2016-10-05T12:33:01Z
        displayName: Since date
        description: Only return logged requests after this date

    responses:
      200:
        body:
          application/json:
            example: !include examples/serve-events.example.json
  delete:
    description: Delete all received requests
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /{requestId}:
    description: Single logged request
    get:
      responses:
        200:
          body:
            application/json:
              example: !include examples/request.example.json

    uriParameters:
      requestId:
        displayName: Request ID
        description: The UUID of the logged request
        required: true
        example: 12fb14bb-600e-4bfa-bd8d-be7f12562c99

  /reset:
    description: Request journal
    post:
      description: Empty the request journal
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

  /count:
    description: Request journal
    post:
      description: Count requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Number of matching requests
          body:
            application/json:
              example: !include examples/request-count.example.json

  /find:
    post:
      description: Retrieve details of requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Matching request details
          body:
            application/json:
              example: !include examples/requests.example.json

  /unmatched:
    get:
      description: Get details of logged requests that weren't matched by any stub mapping
      responses:
        200:
          description: Unmatched request details
          body:
            application/json:
              example: !include examples/requests.example.json

    /near-misses:
      get:
        description: Retrieve near-misses for all unmatched requests
        responses:
          200:
            description: Top 3 (at most) near misses for each unmatched request
            body:
              application/json:
                example: !include examples/near-misses.example.json

/__admin/near-misses:
  description: Near misses allow querying of received requests or request patterns according to similarity

  /request:
    post:
      description: Find at most 3 near misses for closest stub mappings to the specified request
      body:
        application/json:
          example: !include examples/logged-request.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

  /request-pattern:
    description: Near misses
    post:
      description: Find at most 3 near misses for closest logged requests to the specified request pattern
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

/__admin/settings:
  description: Global settings
  post:
    description: Update global settings
    body:
      application/json:
        example: |
          {
              "fixedDelay": 500
          }

    responses:
      200:
        description: Settings successfully updated

/__admin/shutdown:
  description: Shutdown function
  post:
    description: Shutdown the WireMock server
    responses:
      200:
        description: Server will be shut down

#%RAML 0.8
---
title: WireMock
version: 2.3.2
mediaType: application/json

documentation:
  - title: WireMock admin
    content: |
       The WireMock admin API.

schemas:
  - stubMapping: !include schemas/stub-mapping.schema.json
  - stubMappings: !include schemas/stub-mappings.schema.json
  - requestPattern: !include schemas/request-pattern.schema.json

/__admin/mappings:
  description: Stub mappings

  get:
    description: Get all stub mappings

    queryParameters:
      limit:
        displayName: Query limit
        type: number
        description: The maximum number of results to return
        example: 10
        required: false
      offset:
        displayName: Query offset
        type: number
        description: The start index of the results to return
        example: 25
        required: false

    responses:
      200:
        description: All stub mappings
        body:
          application/json:
            schema: stubMappings
            example: !include examples/stub-mappings.example.json

  post:
    description: Create a new stub mapping
    body:
      application/json:
        example: !include examples/stub-mapping-no-id.example.json
        schema: stubMapping

    responses:
      201:
        description: Successfully created
        body:
          application/json:
            example: !include examples/stub-mapping-with-id.example.json
            schema: stubMapping

  delete:
    description: Delete all stub mappings
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /reset:
      description: Stub mappings
      post:
        description: Reset stub mappings (restore to defaults defined back the backing store)
        responses:
          200:
            description: Successfully reset

  /{stubMappingId}:
    description: Single stub mapping
    get:
      description: Get a single stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/stub-mapping-with-id.example.json
              schema: stubMapping

    uriParameters:
      stubMappingId:
        required: true
        example: 730d3e32-d098-4169-a20c-554c3bedce58
        displayName: Stub mapping ID
        description: The UUID of stub mapping

    put:
      description: Update an existing stub mapping
      body:
        application/json:
          example: !include examples/stub-mapping-no-id.example.json
          schema: stubMapping

      responses:
        200:
          body:
            application/json:
              schema: stubMapping
              example: !include examples/stub-mapping-with-id.example.json

    delete:
      description: Delete a stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/empty.example.json

  /save:
    description: Stub mappings
    post:
      description: Save all persistent stub mappings to the backing store
      responses:
        200:
          description: Successfully removed

/__admin/scenarios:
  description: Scenarios support modelling of stateful behaviour

  /reset:
    description: Scenarios
    post:
      description: Reset the state of all scenarios
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

/__admin/requests:
  description: Logged requests and responses received by the mock service

  get:
    description: Get received requests
    queryParameters:
      limit:
        displayName: Query limit
        description: The maximum number of results to return
        example: 10
      since:
        example: 2016-10-05T12:33:01Z
        displayName: Since date
        description: Only return logged requests after this date

    responses:
      200:
        body:
          application/json:
            example: !include examples/serve-events.example.json

  /{requestId}:
    description: Single logged request
    get:
      responses:
        200:
          body:
            application/json:
              example: !include examples/request.example.json

    uriParameters:
      requestId:
        displayName: Request ID
        description: The UUID of the logged request
        required: true
        example: 12fb14bb-600e-4bfa-bd8d-be7f12562c99

  /reset:
    description: Request journal
    post:
      description: Empty the request journal
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

  /count:
    description: Request journal
    post:
      description: Count requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Number of matching requests
          body:
            application/json:
              example: !include examples/request-count.example.json

  /find:
    post:
      description: Retrieve details of requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Matching request details
          body:
            application/json:
              example: !include examples/requests.example.json

  /unmatched:
    get:
      description: Get details of logged requests that weren't matched by any stub mapping
      responses:
        200:
          description: Unmatched request details
          body:
            application/json:
              example: !include examples/requests.example.json

    /near-misses:
      get:
        description: Retrieve near-misses for all unmatched requests
        responses:
          200:
            description: Top 3 (at most) near misses for each unmatched request
            body:
              application/json:
                example: !include examples/near-misses.example.json

/__admin/near-misses:
  description: Near misses allow querying of received requests or request patterns according to similarity

  /request:
    post:
      description: Find at most 3 near misses for closest stub mappings to the specified request
      body:
        application/json:
          example: !include examples/logged-request.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

  /request-pattern:
    description: Near misses
    post:
      description: Find at most 3 near misses for closest logged requests to the specified request pattern
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

/__admin/settings:
  description: Global settings
  post:
    description: Update global settings
    body:
      application/json:
        example: |
          {
              "fixedDelay": 500
          }

    responses:
      200:
        description: Settings successfully updated

/__admin/shutdown:
  description: Shutdown function
  post:
    description: Shutdown the WireMock server
    responses:
      200:
        description: Server will be shut down