fix /_version example in API docs

fix /_version example in API docs

#%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 http://127.0.0.1:8448/v1.0/_version | jq
      {
        "version": "0.8.0",
        "links": {
          "self": {
            "href": "http://127.0.0.1:8448/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

      ##### 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:
  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.


Add permission handler and global search

#%RAML 0.8
title: preview-spec-core
version: v0.1
baseUri: http://localhost:8080/
protocols: [ HTTP, HTTPS ]
mediaType:  application/json
securedBy: [oauth_2_0]

documentation:
  - title: Home
    content: | #This is a prototype API.
  - title: Getting Started
    content: TODO

securitySchemes:
  - basic:
      type: Basic Authentication
  - oauth_2_0:
      description: |
        OAuth2 is a protocol that lets external apps request authorization to private
        details. This is preferred over Basic Authentication because tokens can be limited to specific
        types of data, and can be revoked by users at any time.
      type: OAuth 2.0
      describedBy:
        headers:
          Authorization:
            description: |
              Used to send a valid OAuth 2 access token. Do not use together with
              the "access_token" query string parameter.
            type: string
        queryParameters:
          access_token:
            description: |
              Used to send a valid OAuth 2 access token. Do not use together with
              the "Authorization" header
            type: string
        responses:
          404:
            description: Unauthorized
      settings:
        authorizationUri: https://localhost:8080/login/oauth/authorize
        accessTokenUri: https://localhost:8080/login/oauth/access_token
        authorizationGrants: [ code ]

traits:
  - localized:
      headers:
        Accept-Language:
          description: The response messages are localized according to the set header value. English and german translations can be provided. Unsupported languages will fallback to english.
  - perm_listable:
      queryParameters:
        perms:
          description: Include user permissions on the object.
          type: boolean
  - nested:
      queryParameters:
        depth:
          description: Limit the depth of nested data in the response.
          type: number
  - sortable:
      queryParameters:
        orderBy:
          description: Set the attribute by which the results should be ordered.

  - paged:
      queryParameters:
        page:
          description: The page to be displayed
          type: number
        per_page:
          description: The amount of items per page
          type: number

  - pagedHeader:
      responses:
        200:
          headers:
             Link:
               description: |
                        A link header will be provided accoring to [RFC5988](http://tools.ietf.org/html/rfc5988#page-6).
               example: |
                        Link: <https://localhost:8080/users?page=3&per_page=100>; rel="next", <https://localhost/users?page=50&per_page=100>; rel="last"

  - searchable:
      queryParameters:
        q:
          description: Optional query parameter
          type: string
          required: false

schemas:
  - UserResponse: !include json/UserResponse.schema.json
  - UserListResponse: !include json/UserListResponse.schema.json
  - UserCreateRequest: !include json/UserCreateRequest.schema.json
  - UserUpdateRequest: !include json/UserUpdateRequest.schema.json

  - GroupResponse: !include  json/GroupResponse.schema.json
  - GroupListResponse: !include json/GroupListResponse.schema.json
  - GroupUpdateRequest: !include json/GroupUpdateRequest.schema.json
  - GroupCreateRequest: !include json/GroupCreateRequest.schema.json

  - RoleResponse: !include json/RoleResponse.schema.json
  - RoleListResponse: !include json/RoleListResponse.schema.json
  - RoleUpdateRequest: !include json/RoleUpdateRequest.schema.json
  - RoleCreateRequest: !include json/RoleCreateRequest.schema.json

  - TagResponse: !include json/TagResponse.schema.json
  - TagUpdateRequest: !include json/TagUpdateRequest.schema.json
  - TagCreateRequest: !include json/TagCreateRequest.schema.json

  - ContentResponse: !include json/ContentResponse.schema.json
  - ContentUpdateRequest: !include json/ContentUpdateRequest.schema.json
  - ContentCreateRequest: !include json/ContentCreateRequest.schema.json

  - ObjectSchemaResponse: !include json/ObjectSchemaResponse.schema.json
  - ObjectSchemaListResponse: !include json/ObjectSchemaListResponse.schema.json
  - ObjectSchemaUpdateRequest: !include json/ObjectSchemaUpdateRequest.schema.json
  - ObjectSchemaCreateRequest: !include json/ObjectSchemaCreateRequest.schema.json

  - ProjectResponse: !include json/ProjectResponse.schema.json
  - ProjectListResponse: !include json/ProjectListResponse.schema.json
  - ProjectUpdateRequest: !include json/ProjectUpdateRequest.schema.json
  - ProjectCreateRequest: !include json/ProjectCreateRequest.schema.json

  - GenericMessageResponse: !include json/GenericMessageResponse.schema.json

#------------------------------------------------------------------------------
# User Verticle
#------------------------------------------------------------------------------
/users:
  displayName: Users
  is: [ localized ]
  description: The users rest endpoint is used for CRUD operations on user objects.
  get:
    is: [ perm_listable, paged, searchable ]
    description: Retrieves a list of **users**

    responses:
      200:
        body:
          application/json:
            schema: UserListResponse
            example: !include json/UserListResponse.example.json

  post:
    description: Create new user
    body:
      application/json:
        schema: UserCreateRequest
        example: !include json/UserCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: UserResponse
            example: !include json/UserResponse.example.json

  /{uuid}:
    get:
      is: [ perm_listable ]
      description: Retrieves a **single user** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: UserResponse
              example: !include json/UserResponse.example.json
    put:
      description: Updates the **user** with the given uuid
      body:
          application/json:
              schema: UserUpdateRequest
              example: !include json/UserUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: UserResponse
              example: !include json/UserResponse.example.json
    delete:
      description: Deletes the **user** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the user with the given uuid to the group
      delete:
        description: Remove the user with the given uuid from the group

#------------------------------------------------------------------------------
# Role Verticle
#------------------------------------------------------------------------------
/roles:
  is: [ localized ]
  displayName: Roles
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a list of roles
    responses:
      200:
        body:
          application/json:
            schema: RoleListResponse
            example: !include json/RoleListResponse.example.json
  post:
    description: Create a new role
    body:
      application/json:
        schema: RoleCreateRequest
        example: !include json/RoleCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: RoleResponse
            example: !include json/RoleResponse.example.json

  /{uuid}:
    get:
      is: [ perm_listable ]
      description: Retrieves a **single role** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: RoleResponse
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a **single role** with the given uuid
      body:
        application/json:
          schema: RoleUpdateRequest
          example: !include json/RoleUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: RoleResponse
              example: !include json/RoleResponse.example.json
    delete:
      description: Deletes a **single role** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the role to the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the role from the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
    /chmod/{uuid}:
      put:
        description: |
          Add role permissions to the given entity. TODO: Add info about recursion and handle bitmark like permission flags
      delete:
        description: |
          Remove role permissions from the given entity. TODO: Add info about recursion and handle bitmark like permission flags

#------------------------------------------------------------------------------
# Group Verticle
#------------------------------------------------------------------------------
/groups:
  is: [ localized, sortable, nested ]
  displayName: Groups
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a **list of groups**
    responses:
      200:
        body:
          application/json:
            schema: GroupListResponse
            example: !include json/GroupListResponse.example.json
  post:
    description: Create a new group
    body:
        application/json:
            schema: GroupCreateRequest
            example: !include json/GroupCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: GroupResponse
            example: !include json/GroupResponse.example.json

  /{uuid}:
    is: [ localized, sortable, nested ]
    get:
      description: Retrieves a **single group** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GroupResponse
              example: !include json/GroupResponse.example.json
    put:
      description: Updates a **single group** with the given uuid
      body:
        application/json:
          schema: GroupUpdateRequest
          example: !include json/GroupUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: GroupResponse
              example: !include json/GroupResponse.example.json
    delete:
      description: Deletes a **single group** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /users/{uuid}:
      put:
        description: Add the user with the given uuid to the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the user with the given uuid from the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the group with the given uuid to the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the group with the given uuid from the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Project Verticle
#------------------------------------------------------------------------------
/projects:
  is: [ localized ]
  displayName: Projects
  get:
    is: [ paged, searchable, sortable, perm_listable ]
    description: Retrieves a list of projects
    responses:
      200:
        body:
          application/json:
            schema: ProjectListResponse
            example: !include json/ProjectListResponse.example.json
      400:
        description: Bad Request
      500:
        description: Internal Server Error
  post:
    description: Create a new project
    body:
      application/json:
        schema: ProjectCreateRequest
        example: !include json/ProjectCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: ProjectResponse
            example: !include json/ProjectResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      is: [ perm_listable ]
      description: Retrieves the **project** with the given uuid.
      body:
        application/json:
          schema: ProjectResponse
          example: !include json/ProjectResponse.example.json
    put:
      description: Update the **project** with the given uuid.
      body:
        application/json:
          schema: ProjectUpdateRequest
          example: !include json/ProjectUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ProjectResponse
              example: !include json/ProjectResponse.example.json
    delete:
      description: Deletes the **project** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Schema Verticle
#------------------------------------------------------------------------------
/schemas:
  is: [ localized ]
  displayName: Schemas
  get:
    is: [ paged , perm_listable ]
    description: Retrieves a **list of object schemas**.
    responses:
      200:
        body:
          application/json:
            example: !include json/ObjectSchemaListResponse.example.json
      400:
        description: Bad Request
      500:
        description: Internal Server Error
  post:
    description: Create the schema
    body:
      application/json:
        schema: ObjectSchemaCreateRequest
        example: !include json/ObjectSchemaCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/ObjectSchemaResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      is: [ perm_listable ]
      description: Retrieves the **schema** with the given uuid.
      responses:
        200:
          body:
            application/json:
              schema: ObjectSchemaResponse
              example: !include json/ObjectSchemaResponse.example.json
    put:
      description: Updates the **schema** with the given uuid
      body:
        application/json:
          schema: ObjectSchemaUpdateRequest
          example: !include json/ObjectSchemaUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/ObjectSchemaResponse.example.json
    delete:
      description: Deletes the **schema** with the given uuid.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /projects/{uuid}:
      put:
        description: Add the schema to the project.
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the schema from the project.
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Content Verticle
#------------------------------------------------------------------------------
/{project_name}/contents:
  displayName: Contents
  /{path_or_uuid}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      path_or_uuid:
        description: |
             Can be either path to the content or the uuid of a single content.
        type: string
    get:
      description: Retrieves the **content** with the given path
      queryParameters:
        lang:
          description: Filter the languages in the form of a list containing [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag) which are separated by comma.
          example: /{project_name}/contents/?lang=de-DE,en-US
        update:
          description: The content will be locked when the *update* parameter is set to true.
          example: /{project_name}/contents/?update=true
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
    post:
      description: Creates the **content** with the given path
      body:
        application/json:
          schema: ContentCreateRequest
          example: !include json/ContentCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
        423:
    put:
      description: Updates the **content** with the given path
      body:
        application/json:
          schema: ContentUpdateRequest
          example: !include json/ContentUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
        423:
    delete:
      description: Deletes the **content** with the given path
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
        423:

#------------------------------------------------------------------------------
# Tag Verticle
#------------------------------------------------------------------------------
/{project_name}/tags:
  displayName: Tags
  uriParameters:
    project_name:
      description: Name of the project
      type: string

  /{path_or_uuid}:
    is: [ perm_listable ]
    uriParameters:
      path_or_uuid:
        description: |
             Can be either path to the content or the uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable, nested ]
      description: Load the **tag** with the given path
      queryParameters:
        depth:
          description: Determines the depth of traversal for fetching nested tags.
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    post:
      description: Create the **tag** in the given path. This does not work when a uuid has been specified instead of a valid path.
      body:
        application/json:
          schema: TagCreateRequest
          example: !include json/TagCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    put:
      description: Update the **tag** with the given path.
      body:
        application/json:
          schema: TagUpdateRequest
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the **tag** with the given path.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Binary Verticle
#------------------------------------------------------------------------------
/{project_name}/binaries:
  displayName: Binaries

  /{path_or_uuid}:
    is: [ localized, perm_listable ]
    get:
      headers:
        Accept:
         description: Can be set to *application/json* or *application/octet-stream*
                      to load either the json representation of the file or its binary contents.
      description: Load the **binary file** with the given path
    post:
      description: Create the **binary file** with the given path
    put:
      description: Update the **binary file** with the given path
    delete:
      description: Delete the **binary file** with the given path
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Search Verticle
#------------------------------------------------------------------------------
/{project_name}/search:
  is: [ localized ]
  displayName: Project Search
  get:

/search:
  is: [ localized ]
  displayName: Global Search
  get:

#------------------------------------------------------------------------------
# Navigation Verticle
#------------------------------------------------------------------------------
/{project_name}/navigation:
  is: [ localized ]
  displayName: Navigation
  get:

#------------------------------------------------------------------------------
# Copy Verticle
#------------------------------------------------------------------------------
/copy/{uuid}/to/{uuid}:
  displayName: Copy
  put:
    description: Copy the object to the second object. Include all nested objects during this process. (TODO enhance documentation)

#------------------------------------------------------------------------------
# Move Verticle
#------------------------------------------------------------------------------
/move/{uuid}/to/{uuid}:
  displayName: Move
  put:

#------------------------------------------------------------------------------
# Admin Verticle
#------------------------------------------------------------------------------
/admin:
  displayName: Admin

  /neo4vertx/restart:
    is: [ localized ]
    description: Restart the neo4vertx verticle
    get:

  /services/{mavenCoordinates}:
    is: [ localized ]
    uriParameters:
      mavenCoordinates:
        description: |
                Maven coordinates for the service. (E.g.: com.gentics.cailun:tagcloud:1.0.1)
        type: string
    post:
      description: Deploy a vertx maven service
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a previouly deployed vertx maven server
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

  /verticles/{class}:
    is: [ localized ]
    uriParameters:
      class:
        description: Name of the verticle class
        type: string
    post:
      description: Deploy a verticle with the given class
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a verticle with the given class
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

  /backup:
    is: [ localized ]
    get:
      description: Invoke the live backup process
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#%RAML 0.8
title: preview-spec-core
version: v0.1
baseUri: http://localhost:8080/
protocols: [ HTTP, HTTPS ]
mediaType:  application/json
securedBy: [oauth_2_0]

documentation:
  - title: Home
    content: | #This is a prototype API.
  - title: Getting Started
    content: TODO

securitySchemes:
  - basic:
      type: Basic Authentication
  - oauth_2_0:
      description: |
        OAuth2 is a protocol that lets external apps request authorization to private
        details. This is preferred over Basic Authentication because tokens can be limited to specific
        types of data, and can be revoked by users at any time.
      type: OAuth 2.0
      describedBy:
        headers:
          Authorization:
            description: |
              Used to send a valid OAuth 2 access token. Do not use together with
              the "access_token" query string parameter.
            type: string
        queryParameters:
          access_token:
            description: |
              Used to send a valid OAuth 2 access token. Do not use together with
              the "Authorization" header
            type: string
        responses:
          404:
            description: Unauthorized
      settings:
        authorizationUri: https://localhost:8080/login/oauth/authorize
        accessTokenUri: https://localhost:8080/login/oauth/access_token
        authorizationGrants: [ code ]

traits:
  - localized:
      headers:
        Accept-Language:
          description: The response messages are localized according to the set header value. English and german translations can be provided. Unsupported languages will fallback to english.
  - nested:
      queryParameters:
        depth:
          description: Limit the depth of nested data in the response.
          type: number
  - sortable:
      queryParameters:
        orderBy:
          description: Set the attribute by which the results should be ordered.

  - paged:
      queryParameters:
        page:
          description: The page to be displayed
          type: number
        per_page:
          description: The amount of items per page
          type: number

  - pagedHeader:
      responses:
        200:
          headers:
             Link:
               description: |
                        A link header will be provided accoring to [RFC5988](http://tools.ietf.org/html/rfc5988#page-6).
               example: |
                        Link: <https://localhost:8080/users?page=3&per_page=100>; rel="next", <https://localhost/users?page=50&per_page=100>; rel="last"

  - searchable:
      queryParameters:
        q:
          description: Optional query parameter
          type: string
          required: false

schemas:
  - UserResponse: !include json/UserResponse.schema.json
  - UserListResponse: !include json/UserListResponse.schema.json
  - UserCreateRequest: !include json/UserCreateRequest.schema.json
  - UserUpdateRequest: !include json/UserUpdateRequest.schema.json

  - GroupResponse: !include  json/GroupResponse.schema.json
  - GroupListResponse: !include json/GroupListResponse.schema.json
  - GroupUpdateRequest: !include json/GroupUpdateRequest.schema.json
  - GroupCreateRequest: !include json/GroupCreateRequest.schema.json

  - RoleResponse: !include json/RoleResponse.schema.json
  - RoleListResponse: !include json/RoleListResponse.schema.json
  - RoleUpdateRequest: !include json/RoleUpdateRequest.schema.json
  - RoleCreateRequest: !include json/RoleCreateRequest.schema.json

  - TagResponse: !include json/TagResponse.schema.json
  - TagUpdateRequest: !include json/TagUpdateRequest.schema.json
  - TagCreateRequest: !include json/TagCreateRequest.schema.json

  - ContentResponse: !include json/ContentResponse.schema.json
  - ContentUpdateRequest: !include json/ContentUpdateRequest.schema.json
  - ContentCreateRequest: !include json/ContentCreateRequest.schema.json

  - ObjectSchemaResponse: !include json/ObjectSchemaResponse.schema.json
  - ObjectSchemaListResponse: !include json/ObjectSchemaListResponse.schema.json
  - ObjectSchemaUpdateRequest: !include json/ObjectSchemaUpdateRequest.schema.json
  - ObjectSchemaCreateRequest: !include json/ObjectSchemaCreateRequest.schema.json

  - ProjectResponse: !include json/ProjectResponse.schema.json
  - ProjectListResponse: !include json/ProjectListResponse.schema.json
  - ProjectUpdateRequest: !include json/ProjectUpdateRequest.schema.json
  - ProjectCreateRequest: !include json/ProjectCreateRequest.schema.json

  - GenericMessageResponse: !include json/GenericMessageResponse.schema.json

#------------------------------------------------------------------------------
# User Verticle
#------------------------------------------------------------------------------
/users:
  is: [ localized ]
  displayName: Users
  description: The users rest endpoint is used for CRUD operations on user objects.
  get:
    is: [ paged, searchable ]
    description: Retrieves a list of **users**

    responses:
      200:
        body:
          application/json:
            schema: UserListResponse
            example: !include json/UserListResponse.example.json

  post:
    description: Create new user
    body:
      application/json:
        schema: UserCreateRequest
        example: !include json/UserCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: UserResponse
            example: !include json/UserResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves a **single role** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: UserResponse
              example: !include json/UserResponse.example.json
    put:
      description: Updates the **user** with the given uuid
      body:
          application/json:
              schema: UserUpdateRequest
              example: !include json/UserUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: UserResponse
              example: !include json/UserResponse.example.json
    delete:
      description: Deletes the **user** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the user with the given uuid to the group
      delete:
        description: Remove the user with the given uuid from the group

#------------------------------------------------------------------------------
# Role Verticle
#------------------------------------------------------------------------------
/roles:
  is: [ localized ]
  displayName: Roles
  get:
    is: [ paged, searchable ]
    description: Retrieves a list of roles
    responses:
      200:
        body:
          application/json:
            schema: RoleListResponse
            example: !include json/RoleListResponse.example.json
  post:
    description: Create a new role
    body:
      application/json:
        schema: RoleCreateRequest
        example: !include json/RoleCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: RoleResponse
            example: !include json/RoleResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves a **single role** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: RoleResponse
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a **single role** with the given uuid
      body:
        application/json:
          schema: RoleUpdateRequest
          example: !include json/RoleUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: RoleResponse
              example: !include json/RoleResponse.example.json
    delete:
      description: Deletes a **single role** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the role to the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the role from the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
    /chmod/{uuid}:
      put:
        description: |
          Add role permissions to the given entity. TODO: Add info about recursion and handle bitmark like permission flags
      delete:
        description: |
          Remove role permissions from the given entity. TODO: Add info about recursion and handle bitmark like permission flags

#------------------------------------------------------------------------------
# Group Verticle
#------------------------------------------------------------------------------
/groups:
  is: [ localized, sortable, nested ]
  displayName: Groups
  get:
    is: [ paged, searchable ]
    description: Retrieves a **list of groups**
    responses:
      200:
        body:
          application/json:
            schema: GroupListResponse
            example: !include json/GroupListResponse.example.json
  post:
    description: Create a new group
    body:
        application/json:
            schema: GroupCreateRequest
            example: !include json/GroupCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: GroupResponse
            example: !include json/GroupResponse.example.json

  /{uuid}:
    is: [ localized, sortable, nested ]
    get:
      description: Retrieves a **single group** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GroupResponse
              example: !include json/GroupResponse.example.json
    put:
      description: Updates a **single group** with the given uuid
      body:
        application/json:
          schema: GroupUpdateRequest
          example: !include json/GroupUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: GroupResponse
              example: !include json/GroupResponse.example.json
    delete:
      description: Deletes a **single group** with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /users/{uuid}:
      put:
        description: Add the user with the given uuid to the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the user with the given uuid from the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the group with the given uuid to the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the group with the given uuid from the group
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Project Verticle
#------------------------------------------------------------------------------
/projects:
  is: [ localized ]
  displayName: Projects
  get:
    is: [ paged, searchable, sortable ]
    description: Retrieves a list of projects
    responses:
      200:
        body:
          application/json:
            schema: ProjectListResponse
            example: !include json/ProjectListResponse.example.json
      400:
        description: Bad Request
      500:
        description: Internal Server Error
  post:
    description: Create a new project
    body:
      application/json:
        schema: ProjectCreateRequest
        example: !include json/ProjectCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            schema: ProjectResponse
            example: !include json/ProjectResponse.example.json

  /{uuid}:
    get:
      description: Retrieves the **project** with the given uuid
    put:
      body:
        application/json:
          schema: ProjectUpdateRequest
          example: !include json/ProjectUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ProjectResponse
              example: !include json/ProjectResponse.example.json
    delete:
      description: Deletes the project with the given uuid
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Schema Verticle
#------------------------------------------------------------------------------
/schemas:
  is: [ localized ]
  displayName: Schemas
  get:
    is: [ paged ]
    description: Retrieves a **list of object schemas**.
    responses:
      200:
        body:
          application/json:
            example: !include json/ObjectSchemaListResponse.example.json
      400:
        description: Bad Request
      500:
        description: Internal Server Error
  post:
    description: Create the schema
    body:
      application/json:
        schema: ObjectSchemaCreateRequest
        example: !include json/ObjectSchemaCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/ObjectSchemaResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves the **schema** with the given uuid.
      responses:
        200:
          body:
            application/json:
              schema: ObjectSchemaResponse
              example: !include json/ObjectSchemaResponse.example.json
    put:
      description: Updates the **schema** with the given uuid
      body:
        application/json:
          schema: ObjectSchemaUpdateRequest
          example: !include json/ObjectSchemaUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/ObjectSchemaResponse.example.json
    delete:
      description: Deletes the **schema** with the given uuid.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /projects/{uuid}:
      put:
        description: Add the schema to the project.
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the schema from the project.
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Content Verticle
#------------------------------------------------------------------------------
/{project_name}/contents:
  displayName: Contents
  /{path_or_uuid}:
    is: [ localized, sortable, nested ]
    uriParameters:
      path_or_uuid:
        description: |
             Can be either path to the content or the uuid of a single content.
        type: string
    get:
      description: Retrieves the **content** with the given path
      queryParameters:
        lang:
          description: Filter the languages in the form of a list containing [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag) which are separated by comma.
          example: /{project_name}/contents/?lang=de-DE,en-US
        update:
          description: The content will be locked when the *update* parameter is set to true.
          example: /{project_name}/contents/?update=true
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
    post:
      description: Creates the **content** with the given path
      body:
        application/json:
          schema: ContentCreateRequest
          example: !include json/ContentCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
        423:
    put:
      description: Updates the **content** with the given path
      body:
        application/json:
          schema: ContentUpdateRequest
          example: !include json/ContentUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
        423:
    delete:
      description: Deletes the **content** with the given path
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
        423:

#------------------------------------------------------------------------------
# Tag Verticle
#------------------------------------------------------------------------------
/{project_name}/tags:
  displayName: Tags
  uriParameters:
    project_name:
      description: Name of the project
      type: string

  /{path_or_uuid}:
    uriParameters:
      path_or_uuid:
        description: |
             Can be either path to the content or the uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable, nested ]
      description: Load the **tag** with the given path
      queryParameters:
        depth:
          description: Determines the depth of traversal for fetching nested tags.
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    post:
      description: Create the **tag** in the given path. This does not work when a uuid has been specified instead of a valid path.
      body:
        application/json:
          schema: TagCreateRequest
          example: !include json/TagCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    put:
      description: Update the **tag** with the given path.
      body:
        application/json:
          schema: TagUpdateRequest
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the **tag** with the given path.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Binary Verticle
#------------------------------------------------------------------------------
/{project_name}/binaries:
  displayName: Binaries

  /{path_or_uuid}:
    is: [ localized ]
    get:
      headers:
        Accept:
         description: Can be set to *application/json* or *application/octet-stream*
                      to load either the json representation of the file or its binary contents.
      description: Load the **binary file** with the given path
    post:
      description: Create the **binary file** with the given path
    put:
      description: Update the **binary file** with the given path
    delete:
      description: Delete the **binary file** with the given path
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Search Verticle
#------------------------------------------------------------------------------
/{project_name}/search:
  is: [ localized ]
  displayName: Search
  get:

#------------------------------------------------------------------------------
# Navigation Verticle
#------------------------------------------------------------------------------
/{project_name}/navigation:
  is: [ localized ]
  displayName: Navigation
  get:

#------------------------------------------------------------------------------
# Copy Verticle
#------------------------------------------------------------------------------
/copy/{uuid}/to/{uuid}:
  displayName: Copy
  put:
    description: Copy the object to the second object. Include all nested objects during this process. (TODO enhance documentation)

#------------------------------------------------------------------------------
# Move Verticle
#------------------------------------------------------------------------------
/move/{uuid}/to/{uuid}:
  displayName: Move
  put:

#------------------------------------------------------------------------------
# Admin Verticle
#------------------------------------------------------------------------------
/admin:
  displayName: Admin

  /neo4vertx/restart:
    is: [ localized ]
    description: Restart the neo4vertx verticle
    get:

  /services/{mavenCoordinates}:
    is: [ localized ]
    uriParameters:
      mavenCoordinates:
        description: |
                Maven coordinates for the service. (E.g.: com.gentics.cailun:tagcloud:1.0.1)
        type: string
    post:
      description: Deploy a vertx maven service
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a previouly deployed vertx maven server
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

  /verticles/{class}:
    is: [ localized ]
    uriParameters:
      class:
        description: Name of the verticle class
        type: string
    post:
      description: Deploy a verticle with the given class
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a verticle with the given class
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

  /backup:
    is: [ localized ]
    get:
      description: Invoke the live backup process
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json


update users.raml to use update-user.json for input schema

description: SDM Users
get:
  description: Return a list of all users
  responses:
    200:
      body:
        application/json:
          example: !include ../examples/user-list.json
          schema: !include ../schemas/output/user-list.json
post:
  description: Add a new user
  is: [validates-json-body]
  body:
    application/json:
      example: !include ../examples/user_jane_doe.json
      schema: !include ../schemas/input/user-new.json
  responses:
    200:
      body:
        application/json:
          example: |
            {"_id": "jane.doe@gmail.com"}
          schema: !include ../schemas/output/user-new.json
/self:
  description:  The currently authenticated user
  get:
    description: Get informatiomn about the current user
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/user_jane_doe.json
            schema: !include ../schemas/output/user.json
/self/avatar:
  description: Current user's avatar
  get:
    description:  Get the avatar of the current user
    responses:
      307:
        description: Redirects to the image file of the current user's avatar
/{UserId}:
  description: Interact with a specific user by ID
  uriParameters:
    UserId:
      type: string
  get:
    description: Get information about the specified user
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/user_jane_doe.json
            schema: !include ../schemas/output/user.json
  put:
    description: Update the specified user
    body:
      application/json:
        description: Accepts an object matching the User type except all fields are optional
        example: |
          {"email":"new_email@test.com"}
        schema: !include ../schemas/input/user-update.json
    responses:
      200:
        body:
          application/json:
            example: |
              {"modified":1}
            schema: !include ../schemas/output/user-update.json
  delete:
    description: Delete a user
    responses:
      200:
        description: User was deleted
        body:
          application/json:
            example: |
              {"deleted":1}
            schema: !include ../schemas/output/user-delete.json
      404:
        description: User not found
/{UserId}/groups:
  description: Groups for the specified user
  uriParameters:
    UserId:
      type: string
  get:
    description: List all groups the specified user is a member of
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/groups_list.json
            schema: !include ../schemas/output/groups-list.json
/{UserId}/avatar:
  description: Avatar for the specified user
  get:
    description:  Get the avatar of the specified user
    responses:
      307:
        description: Redirects to the image file of the specified user's avatar

description: SDM Users
get:
  description: Return a list of all users
  responses:
    200:
      body:
        application/json:
          example: !include ../examples/user-list.json
          schema: !include ../schemas/output/user-list.json
post:
  description: Add a new user
  is: [validates-json-body]
  body:
    application/json:
      example: !include ../examples/user_jane_doe.json
      schema: !include ../schemas/input/user-new.json
  responses:
    200:
      body:
        application/json:
          example: |
            {"_id": "jane.doe@gmail.com"}
          schema: !include ../schemas/output/user-new.json
/self:
  description:  The currently authenticated user
  get:
    description: Get informatiomn about the current user
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/user_jane_doe.json
            schema: !include ../schemas/output/user.json
/self/avatar:
  description: Current user's avatar
  get:
    description:  Get the avatar of the current user
    responses:
      307:
        description: Redirects to the image file of the current user's avatar
/{UserId}:
  description: Interact with a specific user by ID
  uriParameters:
    UserId:
      type: string
  get:
    description: Get information about the specified user
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/user_jane_doe.json
            schema: !include ../schemas/output/user.json
  put:
    description: Update the specified user
    body:
      application/json:
        description: Accepts an object matching the User type except all fields are optional
        example: |
          {"email":"new_email@test.com"}
        schema: !include ../schemas/input/user.json
    responses:
      200:
        body:
          application/json:
            example: |
              {"modified":1}
            schema: !include ../schemas/output/user-update.json
  delete:
    description: Delete a user
    responses:
      200:
        description: User was deleted
        body:
          application/json:
            example: |
              {"deleted":1}
            schema: !include ../schemas/output/user-delete.json
      404:
        description: User not found
/{UserId}/groups:
  description: Groups for the specified user
  uriParameters:
    UserId:
      type: string
  get:
    description: List all groups the specified user is a member of
    responses:
      200:
        body:
          application/json:
            example: !include ../examples/groups_list.json
            schema: !include ../schemas/output/groups-list.json
/{UserId}/avatar:
  description: Avatar for the specified user
  get:
    description:  Get the avatar of the specified user
    responses:
      307:
        description: Redirects to the image file of the specified user's avatar