reformat security section of api docs intro

#%RAML 0.8

title: Ephemeral Container Service (ECS) (%ECS_VERSION%)
version: v99.999
documentation:
  - title: Overview
    content: |
      The Ephemeral Container Service (ECS) was born out of
      the [Cloudfeaster](https://github.com/simonsdave/cloudfeaster.git) project.
      [Docker](https://www.docker.com/) makes it easy to package
      short lived (aka ephemeral) tasks in a docker image and run
      those tasks using
      the [Docker Remote API](https://docs.docker.com/engine/reference/api/docker_remote_api/).
      ECS adds a service on top these building blocks that allows ephemeral tasks
      to be run on a cluster of [CoreOS](https://coreos.com/) machines using a RESTful API.

  - title: Security
    content: |
      ##### In-transit
      All communication with an ECS deployment is done over SSL/TLS.
      The ECS runs on a cluster of [CoreOS](https://coreos.com/) machines
      with a layer 5 (TCP) load balancer running in front of the cluster.
      Layer 5 load balancing is required because [nginx](http://nginx.org)
      is used to terminate SSL/TLS on each node in the cluster.

      ##### At-rest
      The ECS does not persist any data.

      ##### Authentication
      ...

      ##### Authorization
      The ECS is intended to be used a low level, utility service
      sitting behind a higher level abstractions that implements authorization.
      As such, the ECS has no authorization.
      As soon as a requestor is authenticated they are able to access
      any of ECS' endpoints.

  - title: Performance
    content: |
      In the API docs you'll notice a *Performance Expectations* section for
      endpoint operations. These performance expectations describe the expected
      time to perform the requested operation **after** the request has reached
      the service code which implements the operation. In order to estimate expected
      time to perform an operation from your infrastructure, record the time it
      takes to send repeated requests to the ```/_noop``` endpoint and
      add this ```/_noop``` time to the performance expectation described in the
      API docs.

  - title: Scaling
    content: |
      The ECS runs on a cluster of [CoreOS](https://coreos.com/) machines
      with a layer 5 load balancer running in front of the cluster.
      Each node in the cluster runs the ECS service and schedules tasks
      on that node.
      From an ECS point of view, there are no dependancies between nodes and
      as such the ECS cluster is intended to scale horizontally to accommadate
      a broad variety of workloads.

  - title: Endpoint Documentation Conventions
    content: |
      The remainder of this page contains detailed endpoint documentation.
      There are a few conventions used in the endpoint documentation that
      are worth describing.
      * by default ```ephemeral_container_service.py``` starts on
        ```http://127.0.0.1:8448``` in a development environment; in the
        endpoint samples you should notice endpoint URLs start with
        the environment varilable ```ECS_ENDPOINT```; the rational here
        is that after setting the ```ECS_ENDPOINT``` environment variable
        you should be able to copy and paste all the sample requests
        regardless of the ip/port on which ```ephemeral_container_service.py```
        is listening.

/tasks:
  displayName: Tasks
  description: |
    The ```/tasks``` endpoint enables creation and execution of tasks
  post:
    description: |
      Create and execute a task.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < nnn ms

      ##### Example
      ```bash
      >cat echo.json
      {
        "docker_image": "ubuntu",
        "tag": "latest",
        "cmd": [
          "echo",
          "hello world!!!"
        ]
      }
      >curl \
        -s \
        -X POST \
        -H "Content-Type: application/json" \
        --data-binary @echo.json \
        $ECS_ENDPOINT/v1.0/tasks | \
        jq
      {
        "stdout": "aGVsbG8gd29ybGQhISEK",
        "stderr": "",
        "exitCode": 0
      }
      > python
      Python 2.7.6 (default, Jun 22 2015, 17:58:13)
      [GCC 4.8.2] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import base64
      >>> base64.b64decode('aGVsbG8gd29ybGQhISEK')
      'hello world!!!\n'
      >>>
      ```
    responses:
      200:
        description:
          Success!
      400:
        description:
          Bad request.

/_version:
  displayName: Version
  description: |
    The ```/_version``` endpoint reports
    returns the ECS' version.
  get:
    description: |
      The endpoint always returns 200 OK and includes the services'
      version number in the body.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < 50 ms

      ##### Example
      ```bash
      >curl -s $ECS_ENDPOINT/v1.0/_version | jq
      {
        "version": "0.8.0",
        "links": {
          "self": {
            "href": "$ECS_ENDPOINT/v1.0/_version"
          }
        }
      }
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.

/_noop:
  displayName: NoOp
  description: |
    The ```/_noop``` endpoint is intended to be used
    for assessing a deployment's performance.
  get:
    description: |
      The endpoint always returns 200 OK after doing nothing ie. it's a no-op.
      The intended purpose of this endpoint is to measure how long it takes
      for a caller and the service to establish a secure connection
      and complete a request/response roundtrip.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < 50 ms

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        $ECS_ENDPOINT/v1.0/_noop
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.

/_health:
  displayName: Health
  description: |
    An HTTP GET to the ```/_health``` endpoint returns a JSON document
    which describes the health of the service.
  get:
    description: |
      The JSON document returned by an HTTP GET to the ```/_health```
      endpoint and the HTTP status code describe the health of the service.
      An HTTP status code of 200 OK is healthy and anything else is unhealthy.
      The top level "status" property in the JSON document will be "green" if the service
      is healthy and "red" if there's a problem.
      The "details" property of the JSON document contains a red/green style health entry
      for each service's components.
      The overall health is "red" if any of the dependant services are unhealthy.

      Two types of health check are possible. A quick health check
      does not confirm the health of all service components and will
      respond quickly. A comprehensive health check does check
      all service components. The ```quick``` query string parameter
      takes a boolean value to determine if a quick or comprehensive
      health check is performed.

      ##### Authentication
        * None (for now)

      ##### Usage Expectations
        * the external monitoring service will perform a quick health check every minute
        * the external monitoring service will perform a comprehensive health check 5 minutes
        * a load balancer sitting in front of the app tier will repeatedly and
          frequently issue a quick health check

      ##### Performance Expectations
        * quick - 99% of the time < 50 ms
        * comprehensive - 99% of the time < 3,050 ms
          (note 3,050 is determined by taking the default value for the
          ```max_time_in_ms_to_wait_for_component_health_checks```
          configuration option and adding 50 ms ie. changing the
          configuration option can be used to change the performance
          characteristics of the endpoint)

      ##### Example
      For example, below a sample of a healthy response to a request
      for a quick health check.

      ```bash
      >curl \
        -s \
        $ECS_ENDPOINT/v1.0/_health?quick=false | \
        jq
      {
        "status": "green",
        "details": {
          "docker remote api": {
            "status": "green",
            "details": {
              "connectivity": "green",
              "api version": "green"
            }
          }
        },
        "links": {
          "self": {
            "href": "$ECS_ENDPOINT/v1.0/_health"
          }
        }
      }
      >
      ```

    queryParameters:
      quick:
        displayName: quick
        type: boolean
        description:
          Determines if a quick or deep health check is performed.
          quick is true by default.
        example: true
        required: false
    responses:
      200:
        description:
          When everything is green a 200 OK is returned.
      500:
        description:
          something super nasty happened inside the service
      503:
        description:
          When something is red a 503 service unavailable is returned.

#%RAML 0.8

title: Ephemeral Container Service (ECS) (%ECS_VERSION%)
version: v99.999
documentation:
  - title: Overview
    content: |
      The Ephemeral Container Service (ECS) was born out of
      the [Cloudfeaster](https://github.com/simonsdave/cloudfeaster.git) project.
      [Docker](https://www.docker.com/) makes it easy to package
      short lived (aka ephemeral) tasks in a docker image and run
      those tasks using
      the [Docker Remote API](https://docs.docker.com/engine/reference/api/docker_remote_api/).
      ECS adds a service on top these building blocks that allows ephemeral tasks
      to be run on a cluster of [CoreOS](https://coreos.com/) machines using a RESTful API.

  - title: Security
    content: |
      In-transit - All communication with an ECS deployment is done over SSL/TLS.
      The ECS runs on a cluster of [CoreOS](https://coreos.com/) machines
      with a layer 5 (TCP) load balancer running in front of the cluster.
      Layer 5 load balancing is required because [nginx](http://nginx.org)
      is used to terminate SSL/TLS on each node in the cluster.

      At-rest - The ECS does not persist any data.

      Authentication ...

      Authorization - the ECS is intended to be used a low level, utility service
      sitting behind a higher level abstractions that implements authorization.
      As such, the ECS has no authorization.
      As soon as a requestor is authenticated they are able to access
      any of ECS' endpoints.

  - title: Performance
    content: |
      In the API docs you'll notice a *Performance Expectations* section for
      endpoint operations. These performance expectations describe the expected
      time to perform the requested operation **after** the request has reached
      the service code which implements the operation. In order to estimate expected
      time to perform an operation from your infrastructure, record the time it
      takes to send repeated requests to the ```/_noop``` endpoint and
      add this ```/_noop``` time to the performance expectation described in the
      API docs.

  - title: Scaling
    content: |
      The ECS runs on a cluster of [CoreOS](https://coreos.com/) machines
      with a layer 5 load balancer running in front of the cluster.
      Each node in the cluster runs the ECS service and schedules tasks
      on that node.
      From an ECS point of view, there are no dependancies between nodes and
      as such the ECS cluster is intended to scale horizontally to accommadate
      a broad variety of workloads.

  - title: Endpoint Documentation Conventions
    content: |
      The remainder of this page contains detailed endpoint documentation.
      There are a few conventions used in the endpoint documentation that
      are worth describing.
      * by default ```ephemeral_container_service.py``` starts on
        ```http://127.0.0.1:8448``` in a development environment; in the
        endpoint samples you should notice endpoint URLs start with
        the environment varilable ```ECS_ENDPOINT```; the rational here
        is that after setting the ```ECS_ENDPOINT``` environment variable
        you should be able to copy and paste all the sample requests
        regardless of the ip/port on which ```ephemeral_container_service.py```
        is listening.

/tasks:
  displayName: Tasks
  description: |
    The ```/tasks``` endpoint enables creation and execution of tasks
  post:
    description: |
      Create and execute a task.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < nnn ms

      ##### Example
      ```bash
      >cat echo.json
      {
        "docker_image": "ubuntu",
        "tag": "latest",
        "cmd": [
          "echo",
          "hello world!!!"
        ]
      }
      >curl \
        -s \
        -X POST \
        -H "Content-Type: application/json" \
        --data-binary @echo.json \
        $ECS_ENDPOINT/v1.0/tasks | \
        jq
      {
        "stdout": "aGVsbG8gd29ybGQhISEK",
        "stderr": "",
        "exitCode": 0
      }
      > python
      Python 2.7.6 (default, Jun 22 2015, 17:58:13)
      [GCC 4.8.2] on linux2
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import base64
      >>> base64.b64decode('aGVsbG8gd29ybGQhISEK')
      'hello world!!!\n'
      >>>
      ```
    responses:
      200:
        description:
          Success!
      400:
        description:
          Bad request.

/_version:
  displayName: Version
  description: |
    The ```/_version``` endpoint reports
    returns the ECS' version.
  get:
    description: |
      The endpoint always returns 200 OK and includes the services'
      version number in the body.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < 50 ms

      ##### Example
      ```bash
      >curl -s $ECS_ENDPOINT/v1.0/_version | jq
      {
        "version": "0.8.0",
        "links": {
          "self": {
            "href": "$ECS_ENDPOINT/v1.0/_version"
          }
        }
      }
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.

/_noop:
  displayName: NoOp
  description: |
    The ```/_noop``` endpoint is intended to be used
    for assessing a deployment's performance.
  get:
    description: |
      The endpoint always returns 200 OK after doing nothing ie. it's a no-op.
      The intended purpose of this endpoint is to measure how long it takes
      for a caller and the service to establish a secure connection
      and complete a request/response roundtrip.

      ##### Authentication
        * None

      ##### Performance Expectations
        * 99% of the time < 50 ms

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        $ECS_ENDPOINT/v1.0/_noop
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.

/_health:
  displayName: Health
  description: |
    An HTTP GET to the ```/_health``` endpoint returns a JSON document
    which describes the health of the service.
  get:
    description: |
      The JSON document returned by an HTTP GET to the ```/_health```
      endpoint and the HTTP status code describe the health of the service.
      An HTTP status code of 200 OK is healthy and anything else is unhealthy.
      The top level "status" property in the JSON document will be "green" if the service
      is healthy and "red" if there's a problem.
      The "details" property of the JSON document contains a red/green style health entry
      for each service's components.
      The overall health is "red" if any of the dependant services are unhealthy.

      Two types of health check are possible. A quick health check
      does not confirm the health of all service components and will
      respond quickly. A comprehensive health check does check
      all service components. The ```quick``` query string parameter
      takes a boolean value to determine if a quick or comprehensive
      health check is performed.

      ##### Authentication
        * None (for now)

      ##### Usage Expectations
        * the external monitoring service will perform a quick health check every minute
        * the external monitoring service will perform a comprehensive health check 5 minutes
        * a load balancer sitting in front of the app tier will repeatedly and
          frequently issue a quick health check

      ##### Performance Expectations
        * quick - 99% of the time < 50 ms
        * comprehensive - 99% of the time < 3,050 ms
          (note 3,050 is determined by taking the default value for the
          ```max_time_in_ms_to_wait_for_component_health_checks```
          configuration option and adding 50 ms ie. changing the
          configuration option can be used to change the performance
          characteristics of the endpoint)

      ##### Example
      For example, below a sample of a healthy response to a request
      for a quick health check.

      ```bash
      >curl \
        -s \
        $ECS_ENDPOINT/v1.0/_health?quick=false | \
        jq
      {
        "status": "green",
        "details": {
          "docker remote api": {
            "status": "green",
            "details": {
              "connectivity": "green",
              "api version": "green"
            }
          }
        },
        "links": {
          "self": {
            "href": "$ECS_ENDPOINT/v1.0/_health"
          }
        }
      }
      >
      ```

    queryParameters:
      quick:
        displayName: quick
        type: boolean
        description:
          Determines if a quick or deep health check is performed.
          quick is true by default.
        example: true
        required: false
    responses:
      200:
        description:
          When everything is green a 200 OK is returned.
      500:
        description:
          something super nasty happened inside the service
      503:
        description:
          When something is red a 503 service unavailable is returned.