Update doc and add paging info

Update doc and add paging info

#%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
          required: false
  - 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. Please note that page numbering is 1-based and that omitting the page parameter will return the first page 1.
          type: number
        per_page:
          description: The page size. A page size of 25 will be used when this parameter is omitted.
          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
  - TagListResponse: !include json/TagListResponse.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. **Partially implemented** - **Tested**
    responses:
      200:
        body:
          application/json:
            schema: UserListResponse
            example: !include json/UserListResponse.example.json

  post:
    description: Create new user. **Partially implemented** - **Tested**
    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. **Partially implemented** - **Tested**
      responses:
        200:
          body:
            application/json:
              schema: UserResponse
              example: !include json/UserResponse.example.json
    put:
      description: Updates the user with the given uuid. **Partially implemented** - **Tested**
      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. **Partially implemented** - **Tested**
      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. **Partially implemented** - **Not tested**
      delete:
        description: Remove the user with the given uuid from the group. **Partially implemented** - **Not tested**

#------------------------------------------------------------------------------
# Role Verticle
#------------------------------------------------------------------------------
/roles:
  is: [ localized ]
  displayName: Roles
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a list of roles.  **Partially implemented** - **Tested 1**
    responses:
      200:
        body:
          application/json:
            schema: RoleListResponse
            example: !include json/RoleListResponse.example.json
  post:
    description: Create a new role.  **Partially implemented** - **Tested 4**
    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.  **Partially implemented** - **Tested 1**
      responses:
        200:
          body:
            application/json:
              schema: RoleResponse
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a single role with the given uuid.  **Partially implemented** - **Tested 2**
      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.  **Partially implemented** - **Tested 2**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the role to the group. **Omitted**
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the role from the group. **Omitted**
        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. **Not implemented** - **Not tested**
      delete:
        description: |
          Remove role permissions from the given entity. TODO: Add info about recursion and handle bitmark like permission flags. **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# Group Verticle
#------------------------------------------------------------------------------
/groups:
  is: [ localized, sortable, nested ]
  displayName: Groups
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a list of groups. **Not implemented** - **Not tested**
    responses:
      200:
        body:
          application/json:
            schema: GroupListResponse
            example: !include json/GroupListResponse.example.json
  post:
    description: Create a new group. **Not implemented** - **Not tested**
    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.  **Partially implemented** - **Tested 1**
      responses:
        200:
          body:
            application/json:
              schema: GroupResponse
              example: !include json/GroupResponse.example.json
    put:
      description: Updates a single group with the given uuid. **Not implemented** - **Not tested**
      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. **Not implemented** - **Not tested**
      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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
    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. **Partially implemented** - **Tested 1**
    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. **Partially implemented** - **Tested 1**
      body:
        application/json:
          schema: ProjectResponse
          example: !include json/ProjectResponse.example.json
    put:
      description: Update the project with the given uuid. **Partially implemented** - **Tested 1**
      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. **Partially implemented** - **Tested 2**
      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.  **Partially implemented** - **Tested 1**
    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. **Not implemented** - **Not tested**
    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.  **Partially implemented** - **Tested 1**
      responses:
        200:
          body:
            application/json:
              schema: ObjectSchemaResponse
              example: !include json/ObjectSchemaResponse.example.json
    put:
      description: Updates the schema with the given uuid. **Not implemented** - **Not tested**
      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. **Not implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /projects/{uuid}:
      post:
        description: Add the schema to the project. **Not implemented** - **Not tested**
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the schema from the project. **Not implemented** - **Not tested**
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Content Verticle
#------------------------------------------------------------------------------
/{project_name}/contents:
  displayName: Contents
  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all contents.
      responses:
        200:
          body:
            application/json:
              schema: ContentListResponse
              example: !include json/ContentListResponse.example.json
    post:
      description: Create content.
      body:
        application/json:
          schema: ContentCreateRequest
          example: !include json/ContentCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
  /{uuid}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      uuid:
        description: Uuid of a single content.
        type: string
    get:
      description: Retrieves the content with the given uuid. **Not implemented** - **Not tested**
      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
    put:
      description: Updates the content with the given uuid. **Not implemented** - **Not tested**
      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 uuid. **Not implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin/{name}:
      get:
        description: Load the binary property value
      put:
        description: Update the binary property value

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

  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all tags of the project. **Partially implemented**
      responses:
        200:
          body:
            application/json:
              example: !include json/TagListResponse.example.json
    post:
      description: Create a new tag. **Partially implemented**
      body:
        application/json:
          schema: TagCreateRequest
          example: !include json/TagCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json

  /{uuid}:
    is: [ perm_listable ]
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable, nested ]
      description: Load the tag with the given uuid. **Partially implemented** - **Tested 7**
      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
    put:
      description: Update the tag with the given path. **Partially implemented** - **Tested 4**
      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. **Partially implemented** - **Tested 4**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /tags:
      get:
        description: Load a list of subtags
    /tags/{uuid}:
      uriParameters:
        uuid:
          description: Uuid of a tag.
          type: string
      post:
        description: Assign the tag to the content. **Not implemented**
      delete:
        description: Remove the tag from the content. **Not implemented**
    /contents:
      get:
        description: Load a list of contents that have been taged with the tag.
    /contents/{uuid}:
      uriParameters:
        uuid:
          description: Uuid of a content.
          type: string
      post:
        description: Assign the tag to the content. **Not implemented**
      delete:
        description: Remove the tag from the content. **Not implemented**

    /bin/{name}:
      get:
        description: Load the binary property value
      put:
        description: Update the binary property value

#------------------------------------------------------------------------------
# WebRoot Verticle
#------------------------------------------------------------------------------

/{project_name}/webroot:
  is: [ localized ]
  displayName: WebRoot
  /{path}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      path:
        description: Path to a content or tag.
        type: string
    get:
      description: Retrieves the content with the given path. **Not implemented** - **Not tested**
      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

#------------------------------------------------------------------------------
# Search Verticle
#------------------------------------------------------------------------------
/{project_name}/search:
  is: [ localized ]
  displayName: Project Search
  get:
    description: Query for various objects.  **Not implemented** - **Not tested**

/search:
  is: [ localized ]
  displayName: Global Search
  get:
    description: Query for various objects.  **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# Navigation Verticle
#------------------------------------------------------------------------------
/{project_name}/navigation:
  is: [ localized ]
  displayName: Navigation
  get:
    description: Return the navigation. **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# 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). **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# Move Verticle
#------------------------------------------------------------------------------
/move/{uuid}/to/{uuid}:
  displayName: Move
  put:
    description: Move entities. **Not implemented** - **Not tested**

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

  /neo4vertx/restart:
    is: [ localized ]
    description: Restart the neo4vertx verticle. **Implemented** - **Not tested**
    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. **Partially implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a previouly deployed vertx maven server. **Partially implemented** - **Not tested**
      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. **Partially implemented** - **Not tested**
        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. **Partially implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

  /backup:
    is: [ localized ]
    get:
      description: Invoke the live backup process. **Partially implemented** - **Not tested**
      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.
  - perm_listable:
      queryParameters:
        perms:
          description: Include user permissions on the object.
          type: boolean
          required: false
  - 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
  - TagListResponse: !include json/TagListResponse.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. **Partially implemented** - **Tested**
    responses:
      200:
        body:
          application/json:
            schema: UserListResponse
            example: !include json/UserListResponse.example.json

  post:
    description: Create new user. **Partially implemented** - **Tested**
    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. **Partially implemented** - **Tested**
      responses:
        200:
          body:
            application/json:
              schema: UserResponse
              example: !include json/UserResponse.example.json
    put:
      description: Updates the user with the given uuid. **Partially implemented** - **Tested**
      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. **Partially implemented** - **Tested**
      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. **Partially implemented** - **Not tested**
      delete:
        description: Remove the user with the given uuid from the group. **Partially implemented** - **Not tested**

#------------------------------------------------------------------------------
# Role Verticle
#------------------------------------------------------------------------------
/roles:
  is: [ localized ]
  displayName: Roles
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a list of roles.  **Partially implemented** - **Tested 1**
    responses:
      200:
        body:
          application/json:
            schema: RoleListResponse
            example: !include json/RoleListResponse.example.json
  post:
    description: Create a new role.  **Partially implemented** - **Tested 4**
    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.  **Partially implemented** - **Tested 1**
      responses:
        200:
          body:
            application/json:
              schema: RoleResponse
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a single role with the given uuid.  **Partially implemented** - **Tested 2**
      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.  **Partially implemented** - **Tested 2**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /groups/{uuid}:
      put:
        description: Add the role to the group. **Omitted**
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the role from the group. **Omitted**
        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. **Not implemented** - **Not tested**
      delete:
        description: |
          Remove role permissions from the given entity. TODO: Add info about recursion and handle bitmark like permission flags. **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# Group Verticle
#------------------------------------------------------------------------------
/groups:
  is: [ localized, sortable, nested ]
  displayName: Groups
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a list of groups. **Not implemented** - **Not tested**
    responses:
      200:
        body:
          application/json:
            schema: GroupListResponse
            example: !include json/GroupListResponse.example.json
  post:
    description: Create a new group. **Not implemented** - **Not tested**
    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.  **Partially implemented** - **Tested 1**
      responses:
        200:
          body:
            application/json:
              schema: GroupResponse
              example: !include json/GroupResponse.example.json
    put:
      description: Updates a single group with the given uuid. **Not implemented** - **Not tested**
      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. **Not implemented** - **Not tested**
      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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
        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. **Not implemented** - **Not tested**
    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. **Partially implemented** - **Tested 1**
    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. **Partially implemented** - **Tested 1**
      body:
        application/json:
          schema: ProjectResponse
          example: !include json/ProjectResponse.example.json
    put:
      description: Update the project with the given uuid. **Partially implemented** - **Tested 1**
      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. **Partially implemented** - **Tested 2**
      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.  **Partially implemented** - **Tested 1**
    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. **Not implemented** - **Not tested**
    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.  **Partially implemented** - **Tested 1**
      responses:
        200:
          body:
            application/json:
              schema: ObjectSchemaResponse
              example: !include json/ObjectSchemaResponse.example.json
    put:
      description: Updates the schema with the given uuid. **Not implemented** - **Not tested**
      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. **Not implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /projects/{uuid}:
      post:
        description: Add the schema to the project. **Not implemented** - **Not tested**
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the schema from the project. **Not implemented** - **Not tested**
        responses:
          200:
            body:
              application/json:
                schema: GenericMessageResponse
                example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Content Verticle
#------------------------------------------------------------------------------
/{project_name}/contents:
  displayName: Contents
  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all contents.
      responses:
        200:
          body:
            application/json:
              schema: ContentListResponse
              example: !include json/ContentListResponse.example.json
    post:
      description: Create content.
      body:
        application/json:
          schema: ContentCreateRequest
          example: !include json/ContentCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: ContentResponse
              example: !include json/ContentResponse.example.json
  /{uuid}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      uuid:
        description: Uuid of a single content.
        type: string
    get:
      description: Retrieves the content with the given uuid. **Not implemented** - **Not tested**
      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
    put:
      description: Updates the content with the given uuid. **Not implemented** - **Not tested**
      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 uuid. **Not implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin/{name}:
      get:
        description: Load the binary property value
      put:
        description: Update the binary property value

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

  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all tags of the project. **Partially implemented**
      responses:
        200:
          body:
            application/json:
              example: !include json/TagListResponse.example.json
    post:
      description: Create a new tag. **Partially implemented**
      body:
        application/json:
          schema: TagCreateRequest
          example: !include json/TagCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json

  /{uuid}:
    is: [ perm_listable ]
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable, nested ]
      description: Load the tag with the given uuid. **Partially implemented** - **Tested 7**
      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
    put:
      description: Update the tag with the given path. **Partially implemented** - **Tested 4**
      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. **Partially implemented** - **Tested 4**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /tags:
      get:
        description: Load a list of subtags
    /tags/{uuid}:
      uriParameters:
        uuid:
          description: Uuid of a tag.
          type: string
      post:
        description: Assign the tag to the content. **Not implemented**
      delete:
        description: Remove the tag from the content. **Not implemented**
    /contents:
      get:
        description: Load a list of contents that have been taged with the tag.
    /contents/{uuid}:
      uriParameters:
        uuid:
          description: Uuid of a content.
          type: string
      post:
        description: Assign the tag to the content. **Not implemented**
      delete:
        description: Remove the tag from the content. **Not implemented**

    /bin/{name}:
      get:
        description: Load the binary property value
      put:
        description: Update the binary property value

#------------------------------------------------------------------------------
# WebRoot Verticle
#------------------------------------------------------------------------------

/{project_name}/webroot:
  is: [ localized ]
  displayName: WebRoot
  /{path}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      path:
        description: Path to a content or tag.
        type: string
    get:
      description: Retrieves the content with the given path. **Not implemented** - **Not tested**
      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

#------------------------------------------------------------------------------
# Search Verticle
#------------------------------------------------------------------------------
/{project_name}/search:
  is: [ localized ]
  displayName: Project Search
  get:
    description: Query for various objects.  **Not implemented** - **Not tested**

/search:
  is: [ localized ]
  displayName: Global Search
  get:
    description: Query for various objects.  **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# Navigation Verticle
#------------------------------------------------------------------------------
/{project_name}/navigation:
  is: [ localized ]
  displayName: Navigation
  get:
    description: Return the navigation. **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# 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). **Not implemented** - **Not tested**

#------------------------------------------------------------------------------
# Move Verticle
#------------------------------------------------------------------------------
/move/{uuid}/to/{uuid}:
  displayName: Move
  put:
    description: Move entities. **Not implemented** - **Not tested**

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

  /neo4vertx/restart:
    is: [ localized ]
    description: Restart the neo4vertx verticle. **Implemented** - **Not tested**
    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. **Partially implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a previouly deployed vertx maven server. **Partially implemented** - **Not tested**
      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. **Partially implemented** - **Not tested**
        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. **Partially implemented** - **Not tested**
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json

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


Changing description

Changing description

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

/postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: 1337
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: SE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.xml

/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code having Multiple Cities

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: '01156'
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code having Multiple Cities
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.xml

/postalCode/{countryCode}/getAllValidPostalCodes{mediaTypeExtension}:
  displayName: Lookup all postal codes for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.xml

/postalCode/{countryCode}/allValidPostalCodesDetails{mediaTypeExtension}:
  displayName: Lookup all postal codes with details for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes with details for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.xml

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

/postalCode/{countryCode}/getCityAndType/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: 1337
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: SE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/response.xml

/postalCode/{countryCode}/getCitiesAndTypes/{postalCode}{mediaTypeExtension}:
  displayName: Lookup Postal Code having Multiple Cities

  uriParameters:
    postalCode:
      displayName: Postal code
      type: string
      required: true
      example: '01156'
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup Postal Code having Multiple Cities
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForMultipleCities.xml

/postalCode/{countryCode}/getAllValidPostalCodes{mediaTypeExtension}:
  displayName: Lookup all postal codes for Norway, Sweden, Denmark or Finland

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes for Norway, Sweden, Denmark or Finland
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodes.xml

/postalCode/{countryCode}/allValidPostalCodesDetails{mediaTypeExtension}:
  displayName: Lookup all postal codes with details for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen

  uriParameters:
    countryCode:
      displayName: Country
      required: true
      type: string
      default: "NO"
      example: DE
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Lookup all postal codes with details for Norway, Sweden, Denmark, Finland or Svalbard and Jan Mayen
    queryParameters:

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.json
          application/xml:
            examples:
              successful:
                displayName: Successful
                value: !include examples/responseForPostalCodesDetails.xml


Updated api spec

Updated api spec

#%RAML 0.8
title: ChewCrew
version: v1
baseUri: http://chewcrew.io/{version}

/preferences:
  /categories:
    get:
      description: Get all category type preferences (BBQ, Chinese, Pizza, etc.)

/sessions:
  post:
    description: Create a voting session
    responses:
      200:
        body:
          application/json:
            schema: |
              {
              "$schema": "http://json-schema.org/schema",
              "type": "object",
              "description": "A voting session",
              "properties": {
              "sessionId": "Session UUID",
              "sessionId": { "type": "string" }
              }}
  /{id}:
    /start:
      post:
        description: Starts the voting session
        queryParameters:
          voterId:
            description: Voter UUID to identify the session host
    /end:
      post:
        description: Forcefully ends a voting session
        queryParameters:
          voterId:
            description: Voter UUID to identify the session host
    put:
      description: Update a voting session (will be done when voters first enter a session)
      queryParameters:
        name:
          description: Voters name
        preferences:
          description: Preferences to add
      responses:
        200:
          body:
            application/json:
              schema: |
                {
                "$schema": "http://json-schema.org/schema",
                "type": "object",
                "description": "Voter UUID",
                "properties": {
                "voterId": "UUID assigned to this voter",
                "voterId": {"type": "string"}
                }}
    get:
      description: Retrieve a voting session
      responses:
        200:
          body:
            application/json:
              schema: |
                {
                "$schema": "http://json-schema.org/schema",
                "type": "object",
                "description": "A voting session",
                "properties": {
                "voterId": "Current voters UUID. Will be populated if voter has Put their preferences.",
                "voterId": {"type": "string"},
                "voters": "Total number of unique voters participating",
                "voters": {
                  "type": "array",
                  "name": {"type": "string"}
                  },
                "voted": "Total number of current votes",
                "voted": {"type": "int"},
                "choices": "Voting choices. Will be populated when the voting session has started.",
                "choices": {
                  "type": "array",
                  "items": {"type" : "string"},
                  "minItems": 3,
                  "uniqueItems": true
                  },
                "result": "The winning result. Will be populated when all users have voted or the session has ended.",
                "result": {"type": "string"}
                }}
    post:
      description: Submit a vote to a voting session
      queryParameters:
        choice:
          description: Vote to submit
        voterId:
          description: UUID of voter

#%RAML 0.8
title: ChewCrew
version: v1
baseUri: http://chewcrew.io/{version}

/preferences:
  /categories:
    get:
      description: Get all category type preferences (BBQ, Chinese, Pizza, etc.)

/sessions:
  post:
    description: Create a voting session
    responses:
      200:
        body:
          application/json:
            schema: |
              {
              "$schema": "http://json-schema.org/schema",
              "type": "object",
              "description": "A voting session",
              "properties": {
              "session": "Session UUID",
              "session": { "type": "string" }
              }}
  /{id}:
    /start:
      post:
        description: Starts the voting session
    /end:
      post:
        description: Forcefully ends a voting session
    get:
      description: Retrieve a voting session
      responses:
        200:
          body:
            application/json:
              schema: |
                {
                "$schema": "http://json-schema.org/schema",
                "type": "object",
                "description": "A voting session",
                "properties": {
                "voters": "Total number of unique voters participating",
                "voters": {
                  "type": "array",
                  "name": {"type": "string"}
                  },
                "voted": "Total number of current votes",
                "voted": {"type": "int"},
                "choices": "Voting choices. Will be populated when the voting session has started.",
                "choices": {
                  "type": "array",
                  "items": {"type" : "string"},
                  "minItems": 3,
                  "uniqueItems": true
                  },
                "result": "The winning result. Will be populated when all users have voted or the session has ended.",
                "result": {"type": "string"}
                }}
    put:
      description: Update a voting session (will be done when voters first enter a session)
      queryParameters:
        name:
          description: Voters name
        preferences:
          description: Preferences to add
      responses:
        200:
          body:
            application/json:
              schema: |
                {
                "$schema": "http://json-schema.org/schema",
                "type": "object",
                "description": "Voter UUID",
                "properties": {
                "voterId": "Current voters assigned unique UUID",
                "voterId": {"type": "string"}
                }}
    post:
      description: Submit a vote to a voting session
      queryParameters:
        choice:
          description: Vote to submit
        voterId:
          description: UUID of voter


added searchable trait;

added searchable trait;

#%RAML 0.8
title: CPDN REST API
version: v1
baseUri: https://api.cpdn.sd2.cz/{version}
mediaType: application/json
protocols: [ HTTPS ]
securedBy: [oauth_2_0]

securitySchemes:
  - oauth_2_0: !include schemes/oauth2.raml

resourceTypes:
  - collection: !include types/collection.raml
  - collection-item-read: !include types/collection-item-read.raml
  - collection-item-read-update: !include types/collection-item-read-update.raml
  - collection-item-read-update-delete: !include types/collection-item-read-update-delete.raml

traits:
  - paged: !include traits/paged.raml
  - searchable: !include traits/searchable.raml

/schemes:
  description: Scheme root resource
  /{scheme_id}:
    /nodes:
    /sections:
    /requests:
    /mapPoints:
    /permissions:

/nodes:
  description: Node root resource
  is: [ paged, searchable ]
  type:
    collection:
      exampleCollection: !include samples/read-body/nodes.json
      exampleCreateItem: !include samples/create-body/node.json
  /{node_id}:
    type:
        collection-item-read-update-delete:
          exampleReadItem: !include samples/read-body/node.json
          exampleUpdateItem: !include samples/update-body/node.json
    /calc:
      type:
        collection-item-read-update:
          exampleReadItem: !include samples/read-body/node-calc.json
          exampleUpdateItem: !include samples/update-body/node-calc.json
    /mapPoint:
      type:
        collection-item-read:
          exampleReadItem: !include samples/read-body/node-mapPoint.json
    /scheme:
      type:
        collection-item-read:
          exampleReadItem: !include samples/read-body/node-scheme.json
    /spec:
      type:
        collection-item-read-update:
          exampleReadItem: !include samples/read-body/node-spec.json
          exampleUpdateItem: !include samples/update-body/node-spec.json

/sections:
  description: Section root resource
  /{section_id}:
    /calc:
    /nodes:
    /paths:
    /scheme:
    /spec:

/mapPoints:
  description: MapPoint root resource
  /{mapPoint_id}:
    /node:
    /paths:
      /src:
      /dst:
    /scheme:

/paths:
  description: Path root resource
  /{path_id}:
    /section:

/permissions:
  description: Schema permissions root resource

#%RAML 0.8
title: CPDN REST API
version: v1
baseUri: https://api.cpdn.sd2.cz/{version}
mediaType: application/json
protocols: [ HTTPS ]
securedBy: [oauth_2_0]

securitySchemes:
  - oauth_2_0: !include schemes/oauth2.raml

resourceTypes:
  - collection: !include types/collection.raml
  - collection-item-read: !include types/collection-item-read.raml
  - collection-item-read-update: !include types/collection-item-read-update.raml
  - collection-item-read-update-delete: !include types/collection-item-read-update-delete.raml

traits:
  - paged: !include traits/paged.raml

/schemes:
  description: Scheme root resource
  /{scheme_id}:
    /nodes:
    /sections:
    /requests:
    /mapPoints:
    /permissions:

/nodes:
  description: Node root resource
  is: [ paged ]
  type:
    collection:
      exampleCollection: !include samples/read-body/nodes.json
      exampleCreateItem: !include samples/create-body/node.json
  /{node_id}:
    type:
        collection-item-read-update-delete:
          exampleReadItem: !include samples/read-body/node.json
          exampleUpdateItem: !include samples/update-body/node.json
    /calc:
      type:
        collection-item-read-update:
          exampleReadItem: !include samples/read-body/node-calc.json
          exampleUpdateItem: !include samples/update-body/node-calc.json
    /mapPoint:
      type:
        collection-item-read:
          exampleReadItem: !include samples/read-body/node-mapPoint.json
    /scheme:
      type:
        collection-item-read:
          exampleReadItem: !include samples/read-body/node-scheme.json
    /spec:
      type:
        collection-item-read-update:
          exampleReadItem: !include samples/read-body/node-spec.json
          exampleUpdateItem: !include samples/update-body/node-spec.json

/sections:
  description: Section root resource
  /{section_id}:
    /calc:
    /nodes:
    /paths:
    /scheme:
    /spec:

/mapPoints:
  description: MapPoint root resource
  /{mapPoint_id}:
    /node:
    /paths:
      /src:
      /dst:
    /scheme:

/paths:
  description: Path root resource
  /{path_id}:
    /section:

/permissions:
  description: Schema permissions root resource