add example JSON for /api/annotations; refs #14

#%RAML 0.8
title: OpenBEL API
version: 0.0.2
baseUri: http://next.belframework.org
schemas:
  - annotation:                            !include http://next.belframework.org/schema/annotation.schema.json
  - annotation_collection:                 !include http://next.belframework.org/schema/annotation_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_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
/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
    get:
      description: Retrieves all annotation resources.
      responses:
        200:
          body:
            application/json:
              schema:  annotation_collection
              example: !include http://next.belframework.org/example/annotation_collection.example.json
    /{annotation}:
      description: Represents a single annotation resource.
      options:
        description: Returns allowable HTTP methods.
        responses:
          200:
            headers:
              Accept:
                description: Allowable HTTP methods.
                type:        string
      get:
        description: Retrieves an annotation resource.
      /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
        /{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
          get:
            description:
        /match-results/{match}:
          description: Represents a resource collection of match_results for annotation values.
          uriParameters:
            match:
              type: string
              description: A string to match against the properties of an annotation. This includes identifier, name, and synonyms.
              required: true
          options:
            description: Returns allowable HTTP methods.
            responses:
              200:
                headers:
                  Accept:
                    description: Allowable HTTP methods.
                    type:        string
          get:
            description: Returns a match_results resource collection that represent annotation values found by *{match}*.
            responses:
              200:
                body:
                  application/json:
                    schema: match_result_collection
  /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
    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.

        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 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",
            "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.
      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.
          example: 100
          required: false
        size:
          type: integer
          description: |
            The size of the evidence resource collection to retrieve. This will return a clice of the evidence resource collection relative to *start*.
          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
        faceted:
          type: string
          description: |
            The boolean indicator to provided faceted results for the evidence resource collection. The default is to not facet.
          enum: [ 'true', 'yes', '1', 'on' ]
          example: yes
      responses:
        200:
          description: |
            An example request for this resource might be:

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

          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
      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
    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
    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
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /namespaces:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/equivalents:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/orthologs:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/{value}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/equivalents/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/orthologs/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
# 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:
  - annotation:               !include http://next.belframework.org/schema/annotation.schema.json
  - annotation_collection:    !include http://next.belframework.org/schema/annotation_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_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
/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
          body:
            application/json:
              schema: annotation_collection
    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
      get:
        description: Retrieves an annotation resource.
      /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
        /{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
          get:
            description:
        /match-results/{match}:
          description: Represents a resource collection of match_results for annotation values.
          uriParameters:
            match:
              type: string
              description: A string to match against the properties of an annotation. This includes identifier, name, and synonyms.
              required: true
          options:
            description: Returns allowable HTTP methods.
            responses:
              200:
                headers:
                  Accept:
                    description: Allowable HTTP methods.
                    type:        string
          get:
            description: Returns a match_results resource collection that represent annotation values found by *{match}*.
            responses:
              200:
                body:
                  application/json:
                    schema: match_result_collection
  /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
    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.

        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 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",
            "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.
      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.
          example: 100
          required: false
        size:
          type: integer
          description: |
            The size of the evidence resource collection to retrieve. This will return a clice of the evidence resource collection relative to *start*.
          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
        faceted:
          type: string
          description: |
            The boolean indicator to provided faceted results for the evidence resource collection. The default is to not facet.
          enum: [ 'true', 'yes', '1', 'on' ]
          example: yes
      responses:
        200:
          description: |
            An example request for this resource might be:

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

          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
      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
    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
    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
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /namespaces:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/equivalents:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/orthologs:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
    post:
  /namespaces/{namespace}/{value}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/equivalents/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
  /namespaces/{namespace}/{value}/orthologs/{target}:
    options:
      description: Returns allowable HTTP methods.
      responses:
        200:
          headers:
            Accept:
              description: Allowable HTTP methods.
              type:        string
# vim: ft=yaml sw=2 ts=2 sts=2 expandtab:


Documenting iBoxen (parcel locker pilot in Sweden)

#%RAML 1.0
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox (address, postalCode) and visiting address (visitingAddress, visitingPostalCode). Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk (manned)
        - Type 19 : Posten pakkeutlevering (manned)
        - Type 21 : Postkontor (manned)
        - Type 32 : Postpunkt (manned)
        - Type 37 : Pakkeboks (unmanned)

      Sweden :
        - Type 34 : Manned
        - Type 38 : Locker

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.json
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.json
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.json
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.json
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.json
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
          application/xml:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.xml
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.xml
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.xml
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.xml
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.xml
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.json
          application/xml:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.json
          application/xml:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.xml

#%RAML 1.0
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox (address, postalCode) and visiting address (visitingAddress, visitingPostalCode). Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk (manned)
        - Type 19 : Posten pakkeutlevering (manned)
        - Type 21 : Postkontor (manned)
        - Type 32 : Postpunkt (manned)
        - Type 37 : Pakkeboks (unmanned)

      Sweden :
        - Type 34 : Manned

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.json
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.json
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.json
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.json
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.json
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
          application/xml:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.xml
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.xml
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.xml
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.xml
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.xml
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.json
          application/xml:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.json
          application/xml:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.xml


Define RAML for POST of EnvEntry

Define RAML for POST of EnvEntry

#%RAML 0.8
title: Okapi Core API
version: 0.1
baseUri: https://okapi.cloud
## mediaType:  application/json
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json

#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

# DEPLOYMENT SERVICE

/_/deployment/modules:
  post:
    description: deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: list all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList

  /{instance_id}:
    get:
      description: retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
    delete:
      description: shutdown instance
      responses:
        204:

# DISCOVERY SERVICE

/_/discovery/modules:
  post:
    description: register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: return all instances
    responses:
      200:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: list all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
        400:
          description: Bad Request
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
      put:
        description: update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
      delete:
        description: remove registration for a given instance
        responses:
          204:

/_/discovery/health:
  get:
    description: get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
/_/discovery/nodes:
  get:
    description: get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{node_id}:
    get:
      description: get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

# PROXY SERVICE

/_/proxy/modules:
  post:
    description: announce new module to the proxy, once successful a module
      can be selected for a specific tenant
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: list all available modules
    responses:
      200:
        body:
          application/json:
            schema: ModuleList

  /{module_id}:
    get:
      description: retrieve descriptor for a particular module
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    delete:
      description: remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:

/_/proxy/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
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: list all tenants
    responses:
      200:
        description: list of tenants in a brief format
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: retrieve a tenant
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: remove a tenant
      responses:
        204:

    /modules:
      get:
        description: selection of modules by the tenant
        responses:
          200:
            body:
              application/json:
                schema: TenantModuleDescriptorList
      post:
        description: enable a module for a specified tenant
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          200:
            body:
              application/json:
                schema: TenantModuleDescriptor

      /{module_tenant_id}:
        get:
          description: look up particular module selection
          responses:
            200:
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        delete:
          description: remove particular module selection
          responses:
            204:
/_/proxy/health:
  get:
    description: Check health of all modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
      500:
        description: Server Error

/_/env:
  post:
    description: add envionment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the env entry instance
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: get list of all environment
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: get info for one env var
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: remove a env var
      responses:
        204:

#TODO implement single module health check

#%RAML 0.8
title: Okapi Core API
version: 0.1
baseUri: https://okapi.cloud
## mediaType:  application/json
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json

#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

# DEPLOYMENT SERVICE

/_/deployment/modules:
  post:
    description: deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: list all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList

  /{instance_id}:
    get:
      description: retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
    delete:
      description: shutdown instance
      responses:
        204:

# DISCOVERY SERVICE

/_/discovery/modules:
  post:
    description: register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: return all instances
    responses:
      200:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: list all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
        400:
          description: Bad Request
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
      put:
        description: update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
      delete:
        description: remove registration for a given instance
        responses:
          204:

/_/discovery/health:
  get:
    description: get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
/_/discovery/nodes:
  get:
    description: get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{node_id}:
    get:
      description: get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

# PROXY SERVICE

/_/proxy/modules:
  post:
    description: announce new module to the proxy, once successful a module
      can be selected for a specific tenant
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: list all available modules
    responses:
      200:
        body:
          application/json:
            schema: ModuleList

  /{module_id}:
    get:
      description: retrieve descriptor for a particular module
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          body:
            application/json:
              schema: ModuleDescriptor
    delete:
      description: remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:

/_/proxy/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
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: list all tenants
    responses:
      200:
        description: list of tenants in a brief format
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: retrieve a tenant
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: remove a tenant
      responses:
        204:

    /modules:
      get:
        description: selection of modules by the tenant
        responses:
          200:
            body:
              application/json:
                schema: TenantModuleDescriptorList
      post:
        description: enable a module for a specified tenant
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          200:
            body:
              application/json:
                schema: TenantModuleDescriptor

      /{module_tenant_id}:
        get:
          description: look up particular module selection
          responses:
            200:
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        delete:
          description: remove particular module selection
          responses:
            204:
/_/proxy/health:
  get:
    description: Check health of all modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
      500:
        description: Server Error

/_/env:
  get:
    description: get list of all environment
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: get info for one env var
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: remove a env var
      responses:
        204:

#TODO implement single module health check