add friendly endpoint names in api doc

add friendly endpoint names in api doc

#%RAML 0.8

title: Ephemeral Container Service (ECS) (%ECS_VERSION%)
version: v99.999
documentation:
  - title: Overview
    content: |
      * ...
  - title: Key Concepts
    content: |
      * task packaged inside a docker container
      * emphemeral = short lived, no state

/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 \
        http://127.0.0.1:8445/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!
        body:
          application/json:
            schema: !include ../ecs/jsonschemas/create_tasks_request.json
      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

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        http://127.0.0.1:8445/v1.0/_version
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.
        body:
          application/json:

/_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

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

/_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 \
        http://127.0.0.1:8445/v1.0/_health?quick=false | \
        jq
      {
        "status": "green",
        "details": {
          "docker remote api": {
            "status": "green",
            "details": {
              "connectivity": "green",
              "api version": "green"
            }
          }
        },
        "links": {
          "self": {
            "href": "http://127.0.0.1:8445/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: |
      * ...
  - title: Key Concepts
    content: |
      * task packaged inside a docker container
      * emphemeral = short lived, no state

/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 \
        http://127.0.0.1:8445/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!
        body:
          application/json:
            schema: !include ../ecs/jsonschemas/create_tasks_request.json
      400:
        description:
          Bad request.

/_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

      ##### Example
      ```bash
      >curl \
        -s \
        -o /dev/null \
        -w %{http_code}\\n \
        http://127.0.0.1:8445/v1.0/_version
      200
      >
      ```
    responses:
      200:
        description:
          200 OK is always returned by this endpoint.
        body:
          application/json:

/_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

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

/_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 \
        http://127.0.0.1:8445/v1.0/_health?quick=false | \
        jq
      {
        "status": "green",
        "details": {
          "docker remote api": {
            "status": "green",
            "details": {
              "connectivity": "green",
              "api version": "green"
            }
          }
        },
        "links": {
          "self": {
            "href": "http://127.0.0.1:8445/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.


More work on api.raml

More work on api.raml

[ci skip]

#%RAML 1.0
title: Circular Works
version: v1
baseUri: http://api.circular.works
/tasks:
  get:
    # TODO authentication
    responses:
      200:
        body:
          application/json:
            # Example for showing the index in the app. Maybe we should use a param for this case?
            example: |
              [
                {
                  "title": "Cleaning the space",
                  "recurrence": 2,
                  "current_turn": [
                    {
                      "id": 3,
                      "groups": [
                        {
                          "id": 4,
                          "name": "Pepe y Lola"
                        }
                      ]
                    }
                  ]
                },
                {
                  "title": "Monthly meeting",
                  "recurrence": 3
                }
              ]
  post:
    # TODO authentication
    body:
      application/json:
        example: |
          {
            "title": "Cleaning the space",
            "description": "Weekly cleaning of the space",
            "recurrence": 2,
            "turns": [
              {
                "order": 1,
                "groupIds": [ 4, 7]
              },
              {
                "order": 2,
                "groupIds": [ 10 ]
              }
            ],
            "email": "space@lists.mat.com",
            "notification_subject": "@responsible_users have to clean the space",
            "notification_body": "This is the monthly reminder for @responsible_users to clean the space"
          }
  /{taskId}:
    get:
      # TODO authentication
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "id": 7,
                  "title": "Cleaning the space",
                  "description": "Weekly cleaning of the space",
                  "recurrence": 2,
                  "email": "space@lists.mat.com",
                  "notification_subject": "@responsible_users have to clean the space",
                  "notification_body": "This is the monthly reminder for @responsible_users to clean the space",
                  "turns": [
                    {
                      "id": 7,
                      "order": 1,
                      "groups": [
                        {
                          "id": 4,
                          "name": "Pepe y Lola",
                        },
                        {
                          id: 7,
                          "name": "Lucas",
                        }
                      ]
                    },
                    {
                      "id": 3,
                      "order": 2,
                      "groups": [
                        {
                          "id": 10,
                          "name": "Facundo el de las pipas"
                        }
                      ]
                    }
                  ]
                }
    delete:
    patch:
      body:
        application/json:
          example: |
            {
              "title": "A new title for this task"
            }
/turns:
  /{turnId}:
    patch:
      body:
        application/json:
          example: |
            {
              order: 3
            }
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "id": 3,
                  "order": 3,
                  "groups" : [
                    {
                      "id": 10,
                      "name": "Facundo el de las pipas"
                    }
                  ]
                }
/groups:
  post:
    body:
      application/json:
        example: |
          {
            "name": "Pepe y Lola",
            "emails": [
              "pepe@mat.com",
              "lola.mat.com"
            ]
          }
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "id": 3,
                "name": "Pepe y Lola"
              }
  /{groupId}:
    get:
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "id": 3,
                  "name: "Pepe y Lola"
                }

#%RAML 1.0
title: Circular Works
version: v1
baseUri: http://api.circular.works
/tasks:
  get:
    # TODO authentication
    body:
      application/json:
        # Example for showing the index in the app. Maybe we should use a param for this case?
        example: |
          [
            {
              "title": "Cleaning the space",
              "recurrence": 2,
              "current_turn": [
                {
                  "id": 3,
                  "name": "Pepe y Lola"
                }
              ]
            },
            {
              "title": "Monthly meeting",
              "recurrence": 3
            }
          ]

  post:
    # TODO authentication
    body:
      application/json:
        example: |
          {
            "title": "Cleaning the space",
            "description": "Weekly cleaning of the space",
            "recurrence": 2,
            "turns": [
              [
                # A new group inside a turn
                {
                  "name": "Pepe y Lola",
                  # Force array or allow \n and , ?
                  "emails": "pepe@mat.com\nlola.mat.com"
                },
                # An existing group inside a turn
                {
                  id: 3
                }
              ]
            ],
            "email": "space@lists.mat.com",
            "notification_subject": "@responsible_users have to clean the space",
            "notification_body": "This is the monthly reminder for @responsible_users to clean the space"
          }
  /{taskId}:
    get:
      # TODO authentication
      body:
        application/json:
          example: |
            {
              "id": 7,
              "title": "Cleaning the space",
              "description": "Weekly cleaning of the space",
              "recurrence": 2,
              "turns": [
                [
                  {
                    "id": 4,
                    "name": "Pepe y Lola",
                    "emails": [
                      "pepe@mat.com",
                      "lola.mat.com"
                    ]
                  },
                  # An existing group inside a turn
                  {
                    id: 3,
                    "name": "Lucas",
                    "emails": [
                      "lucas@mat.com"
                    ]
                  }
                ]
              ],
              "email": "space@lists.mat.com",
              "notification_subject": "@responsible_users have to clean the space",
              "notification_body": "This is the monthly reminder for @responsible_users to clean the space"
            }

    delete:
    patch:
      body:
        application/json:
          example: |
            {
              "title": "A new title for this task"
            }


Added rules filtered by name

Added rules filtered by name

is: [ auth ]
type:
  collection:
    humanName: rule
    schemaBaseName: rule
    exampleGetResponse: !include ../examples/rules/response-array-get.json
    examplePostRequest: !include ../examples/rules/request-post.json
    examplePostError: !include ../examples/rules/response-post-error.json
get:
  securedBy: [ jwt: { type: 'owner' }, test ]
  description: |
    By default, retrieve all the rules that a user can visualize.

    - If an `organizationId` is provided, then all the rules of the organization are
    retrieved. The user must be a member of the organization, otherwise, he will get a `403`.
  queryParameters:
    organizationId:
      description: |
        Filter the rules by organization.

        The user **MUST** be a member of the organization.
      type: integer
      required: true
      example: |
        `organizationId=1`
    name:
      type: string
      required: false
      description: Use this parameter to apply a filter on the name. Can be combined with other parameters.
      example: |
        `name=iFlu%`
  responses:
    403:
      description: If the user is not a member of the organization.
post:
  securedBy: [ jwt: { type: 'owner' }, test ]
  responses:
    403:
      description: If the user is not a member of the organization where the new rule will be defined.

/{ruleId}:
  is: [ auth ]
  type:
    member:
      humanName: rule
      schemaBaseName: rule
      identifierName: ruleId
      exampleGetResponse: !include ../examples/rules/response-get.json
      examplePatchRequest: !include ../examples/rules/request-patch.json
      examplePatchError: !include ../examples/rules/response-patch-error.json
  get:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the rule.
  patch:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the rule.

  delete:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the rule.

is: [ auth ]
type:
  collection:
    humanName: rule
    schemaBaseName: rule
    exampleGetResponse: !include ../examples/rules/response-array-get.json
    examplePostRequest: !include ../examples/rules/request-post.json
    examplePostError: !include ../examples/rules/response-post-error.json
get:
  securedBy: [ jwt: { type: 'owner' }, test ]
  description: |
    By default, retrieve all the rules that a user can visualize.

    - If an `organizationId` is provided, then all the rules of the organization are
    retrieved. The user must be a member of the organization, otherwise, he will get a `403`.
  queryParameters:
    organizationId:
      description: |
        Filter the rules by organization.

        The user **MUST** be a member of the organization.
      type: integer
      required: true
      example: |
        `organizationId=1`
  responses:
    403:
      description: If the user is not a member of the organization.
post:
  securedBy: [ jwt: { type: 'owner' }, test ]
  responses:
    403:
      description: If the user is not a member of the organization where the new rule will be defined.

/{ruleId}:
  is: [ auth ]
  type:
    member:
      humanName: rule
      schemaBaseName: rule
      identifierName: ruleId
      exampleGetResponse: !include ../examples/rules/response-get.json
      examplePatchRequest: !include ../examples/rules/request-patch.json
      examplePatchError: !include ../examples/rules/response-patch-error.json
  get:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the rule.
  patch:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the rule.

  delete:
    securedBy: [ jwt: { type: 'owner' }, test ]
    responses:
      403:
        description: If the user is not a member of the organization that owns the rule.