Remove bogus documentation

Remove bogus documentation

(cherry picked from commit 708e76fac6d57c93f735725e586b2f3f934d60cf)

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

documentation:
  - title: Home
    content: | #This is the Beta API.

securitySchemes:
  - basic:
      type: Basic Authentication

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.

  - expandable:
      queryParameters:
        expandAll:
          description: Expand all fields which can be expanded.
          type: boolean
          required: false
        expand:
          description: Expand the fields with the given name.
          type: string
          required: false

  - translatable:
      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: ?lang=de,en

  - imagehandler:
      queryParameters:
        width:
          description: Set image target width. The height is automatically calculated when the width is omitted.
        height:
          description: Set image target height. The width is automatically calculated when the height is omitted.
        cropx:
          description: Set image crop area x coordinate.
        cropy:
          description: Set image crop area y coordinate.
        cropw:
          description: Set image crop area width.
        croph:
          description: Set image crop area height.

  - sortable:
      queryParameters:
        orderBy:
          description: Set the attribute by which the results should be ordered.

  - include_role_perms:
      queryParameters:
        role:
          description: Set the role uuid which will be used to populate the rolePerms field within the response.

  - 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
        perPage:
          description: The page size. A page size of 25 will be used when this parameter is omitted.
          type: number

  - linkresolver:
      queryParameters:
        resolveLinks:
          description: Set whether links shall be resolved. "off" means no link resolving. "full" will contain the webroot prefix and project name, "medium" will contain the project name and "short" neither webroot prefix nor project name.
          type: string
          enum: ["off", "short", "medium", "full"]
          default: off

#------------------------------------------------------------------------------
# User Verticle
#------------------------------------------------------------------------------
/users:
  displayName: Users
  is: [ localized ]
  description: The users rest endpoint is used for CRUD operations on user objects.
  get:
    is: [ include_role_perms, paged ]
    description: Retrieves a list of users.
    responses:
      200:
        body:
          application/json:
            example: !include json/UserListResponse.example.json

  post:
    description: Create a new user. Please note that users create requests may also contain a node reference which is useful when storing additional data next to the user is required.
    body:
      application/json:
        example: !include json/UserCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/UserResponse.example.json

  /{uuid}:
    get:
      is: [ include_role_perms ]
      description: Retrieves a single user with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json
    put:
      description: Updates the user with the given uuid.
      body:
          application/json:
              example: !include json/UserUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json
    delete:
      description: Deletes the user with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

    /{uuid}/permissions/{pathToElement}:
        uriParameters:
          uuid:
            description: Uuid of the user that should be used to read the permissions.
            type: string
          pathToElement:
            description: Path to the element.
            example: |
                /:userUuid/permissions/projects/:projectUuid/schemas/:schemaUuid
                /:userUuid/permissions/projects/:projectUuid/schemas
                /:userUuid/permissions/projects/:projectUuid/nodes
                /:userUuid/permissions/projects/:projectUuid
            type: string
        get:
          description: |
            Return the user permissions to the given element.
          responses:
            200:
              body:
                application/json:
                  example: !include json/UserPermissionResponse.example.json

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

  /{uuid}:
    get:
      is: [ include_role_perms ]
      description: Retrieves a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a single role with the given uuid.
      body:
        application/json:
          example: !include json/RoleUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    delete:
      description: Deletes a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

  /{uuid}/permissions/{pathToElement}:
    uriParameters:
      uuid:
        description: Uuid of the role that should be used to update the permissions.
        type: string
      pathToElement:
        description: Path to the element.
        example: |
            /:roleUuid/permissions/projects/:projectUuid/schemas/:schemaUuid
            /:roleUuid/permissions/projects/:projectUuid/schemas
            /:roleUuid/permissions/projects/:projectUuid/nodes
            /:roleUuid/permissions/projects/:projectUuid
            /:roleUuid/permissions/projects
        type: string
    get:
      description: |
        Return the role permission to the given element.
      responses:
        200:
          body:
            application/json:
              example: !include json/RolePermissionResponse.example.json
    put:
      description: |
        Update the role permission to the given element and update the permission to the given element. This is useful when it is required to grant certain permissions on a given path segment / object.
      body:
        application/json:
          example: !include json/RolePermissionRequest.example.json

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

  /{uuid}:
    is: [ localized, sortable ]
    get:
      description: Retrieves a single group with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GroupResponse.example.json
    put:
      description: Updates a single group with the given uuid.
      body:
        application/json:
          example: !include json/GroupUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/GroupResponse.example.json
    delete:
      description: Deletes a single group with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /roles:
      get:
        description: List all the roles for the given group.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/GroupListResponse.example.json
    /roles/{uuid}:
      put:
        description: Add the given role to the the group.
      delete:
        description: Remove the given role from the group.
        responses:
          200:
            body:
              application/json:
                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:
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the user with the given uuid from the group.
        responses:
          200:
            body:
              application/json:
                example: !include json/GenericMessageResponse.example.json

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

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

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

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

#------------------------------------------------------------------------------
# Microschema Verticle
#------------------------------------------------------------------------------
/microschemas:
  is: [ localized ]
  displayName: Microschemas
  get:
    is: [ paged, include_role_perms ]
    description: Retrieves a list of microschemas.
    responses:
      200:
        body:
          application/json:
            example: !include json/MicroschemaListResponse.example.json
      400:
        description: Bad Request
      500:
        description: Internal Server Error
  post:
    description: Create the microschema.
    body:
      application/json:
        example: !include json/MicroschemaCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/MicroschemaResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/MicroschemaResponse.example.json
    put:
      description: Updates the microschema with the given uuid.
      body:
        application/json:
          example: !include json/MicroschemaUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/MicroschemaResponse.example.json
    delete:
      description: Deletes the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

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

/{projectName}/webroot:
  is: [ localized, linkresolver ]
  displayName: WebRoot
  /{path}:
    is: [ localized, include_role_perms, imagehandler ]
    uriParameters:
      path:
        description: Path to a node.
        type: string
    get:
      description: Retrieves the node with the given path. Please note that it is also possible to query binary data instead of the node JSON metadata. Binary data will be returned if the targeted node provides a path segment using a binary field.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json

#------------------------------------------------------------------------------
# Node Verticle
#------------------------------------------------------------------------------
/{projectName}/nodes:
  displayName: Nodes
  /:
    get:
      is: [ localized, sortable, paged, expandable, include_role_perms ]
      description: Load all nodes.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeListResponse.example.json
    post:
      description: Create a new node.
      is: [ expandable, include_role_perms ]
      body:
        application/json:
          example: !include json/NodeCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
  /{uuid}:
    is: [ localized, linkresolver ]
    uriParameters:
      uuid:
        description: Uuid of a single node.
        type: string
    get:
      is: [ expandable, include_role_perms, translatable ]
      description: Retrieves the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
    put:
      is: [ expandable, include_role_perms ]
      description: Updates the node with the given uuid.
      body:
        application/json:
          example: !include json/NodeUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
        423:
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin:
      is: [ imagehandler ]
      get:
        description: Load the binary property value.
      put:
        description: Update the binary property value.
      post:
        description: Upload the binary property value.
    /tags:
      is: [ sortable, paged ]
      get:
        description: Load the tags that tag the node.
        responses:
          200:
            body:
              application/json:
                example: !include json/TagListResponse.example.json
    /tags/{tagUuuid}:
      put:
        description: Add the tag to the node.
      delete:
        description: Remove the tag from the node.
    /languages/{languageTag}:
      delete:
        description: Deletes the language from the given node.
        responses:
          200:
            body:
              application/json:
                example: !include json/GenericMessageResponse.example.json
    /children:
      get:
        is: [ localized, sortable, paged, expandable ]
        description: Load child nodes for the given node.
    /moveTo/{targetNodeUuid}:
      uriParameters:
        targetNodeUuid:
          description: Uuid of a the target node. This node will become the new parent of the source node.
          type: string
      put:
        description: Move the node to the given node.
#------------------------------------------------------------------------------
# TagFamily Verticle
#------------------------------------------------------------------------------
/{projectName}/tagFamilies:
  displayName: TagFamilies
  uriParameters:
    projectName:
      description: Name of the project.
      type: string

  /:
    get:
      is: [ localized, sortable, paged, include_role_perms ]
      description: Load all tag families of the project.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagFamilyListResponse.example.json
    post:
      description: Create a new tag family.
      body:
        application/json:
          example: !include json/TagFamilyCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagFamilyResponse.example.json

  /{uuid}:
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag family.
        type: string
    get:
      is: [ localized, sortable, include_role_perms ]
      description: Load the tag family with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag family with the given path.
      body:
        application/json:
          example: !include json/TagFamilyUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagFamilyResponse.example.json
    delete:
      description: Delete the tag family with the given path.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /tags:
      get:
        description: Load all tags which were assigned to this tag family.
        responses:
          200:
            body:
              application/json:
                example: !include json/TagListResponse.example.json

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

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

  /{uuid}:
    is: [ include_role_perms ]
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable ]
      description: Load the tag with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag with the given path.
      body:
        application/json:
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the tag with the given path.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Search Verticle
#------------------------------------------------------------------------------
/search:
  displayName: Search
  /nodes:
    is: [ localized, paged ]
    displayName: Node Search
    post:
        description: Query for nodes. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        body:
            application/json:
        responses:
            200:
                body:
                    application/json:
                        example: !include json/NodeListResponse.example.json
  /tags:
    is: [ localized ]
    displayName: Tag Search
    post:
        description: Query for tags. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/TagListResponse.example.json
  /users:
    is: [ localized ]
    displayName: User Search
    post:
        description: Query for users. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/UserListResponse.example.json
  /groups:
    is: [ localized ]
    displayName: Group Search
    post:
        description: Query for groups. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/GroupListResponse.example.json
  /roles:
    is: [ localized ]
    displayName: Role Search
    post:
        description: Query for roles. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/RoleListResponse.example.json
  /projects:
    is: [ localized ]
    displayName: Project Search
    post:
        description: Query for projects. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/ProjectListResponse.example.json
  /tagFamilies:
    is: [ localized ]
    displayName: TagFamily Search
    post:
        description: Query for tagFamilies. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/TagFamilyListResponse.example.json
  /schemas:
    is: [ localized ]
    displayName: Schema Search
    post:
        description: Query for schemas. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/SchemaListResponse.example.json
  /microschemas:
    is: [ localized ]
    displayName: Microschema Search
    post:
        description: Query for microschemas. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/MicroschemaListResponse.example.json
  /status:
   displayName: Search Status
   get:
     description: Load the search status information.
     responses:
            200:
                body:
                    application/json:
                        example: !include json/SearchStatusResponse.example.json

#------------------------------------------------------------------------------
# Authentication Verticle
#------------------------------------------------------------------------------
/auth:
  displayName: Authentication
  /me:
    get:
      description: Return the user response for the current user.
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json

  /login:
    post:
      description: Login the user using the provided credentials.
      body:
        application/json:
          example: !include json/LoginRequest.example.json
  /logout:
    get:
      description: Logout the user.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Utility Verticle
#------------------------------------------------------------------------------
/utilities:
  displayName: Utilities
  /linkResolver:
    is: [ linkresolver ]
    post:
      queryParameters:
        project:
          description: Project for which the link resolving is done. This is important for invalid links.
          type: string
          default: project
      description: Resolve links in posted content. The content may be plain text, but also JSON.
      body:
        text/plain:
          example: Go to <a href="{{mesh.link('70bb205d44064671bb205d4406f671b3')}}">News</a>
      responses:
        200:
          body:
            text/plain:
              example: Go to <a href="/myproject/news/2016/news.html">News</a>

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

documentation:
  - title: Home
    content: | #This is the Beta API.

securitySchemes:
  - basic:
      type: Basic Authentication

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.

  - expandable:
      queryParameters:
        expandAll:
          description: Expand all fields which can be expanded.
          type: boolean
          required: false
        expand:
          description: Expand the fields with the given name.
          type: string
          required: false

  - translatable:
      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: ?lang=de,en

  - imagehandler:
      queryParameters:
        width:
          description: Set image target width. The height is automatically calculated when the width is omitted.
        height:
          description: Set image target height. The width is automatically calculated when the height is omitted.
        cropx:
          description: Set image crop area x coordinate.
        cropy:
          description: Set image crop area y coordinate.
        cropw:
          description: Set image crop area width.
        croph:
          description: Set image crop area height.

  - sortable:
      queryParameters:
        orderBy:
          description: Set the attribute by which the results should be ordered.

  - include_role_perms:
      queryParameters:
        role:
          description: Set the role uuid which will be used to populate the rolePerms field within the response.

  - 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
        perPage:
          description: The page size. A page size of 25 will be used when this parameter is omitted.
          type: number

  - linkresolver:
      queryParameters:
        resolveLinks:
          description: Set whether links shall be resolved. "off" means no link resolving. "full" will contain the webroot prefix and project name, "medium" will contain the project name and "short" neither webroot prefix nor project name.
          type: string
          enum: ["off", "short", "medium", "full"]
          default: off

#------------------------------------------------------------------------------
# User Verticle
#------------------------------------------------------------------------------
/users:
  displayName: Users
  is: [ localized ]
  description: The users rest endpoint is used for CRUD operations on user objects.
  get:
    is: [ include_role_perms, paged ]
    description: Retrieves a list of users.
    responses:
      200:
        body:
          application/json:
            example: !include json/UserListResponse.example.json

  post:
    description: Create a new user. Please note that users create requests may also contain a node reference which is useful when storing additional data next to the user is required.
    body:
      application/json:
        example: !include json/UserCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/UserResponse.example.json

  /{uuid}:
    get:
      is: [ include_role_perms ]
      description: Retrieves a single user with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json
    put:
      description: Updates the user with the given uuid.
      body:
          application/json:
              example: !include json/UserUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json
    delete:
      description: Deletes the user with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

    /{uuid}/permissions/{pathToElement}:
        uriParameters:
          uuid:
            description: Uuid of the user that should be used to read the permissions.
            type: string
          pathToElement:
            description: Path to the element.
            example: |
                /:userUuid/permissions/projects/:projectUuid/schemas/:schemaUuid
                /:userUuid/permissions/projects/:projectUuid/schemas
                /:userUuid/permissions/projects/:projectUuid/nodes
                /:userUuid/permissions/projects/:projectUuid
            type: string
        get:
          description: |
            Return the user permissions to the given element.
          responses:
            200:
              body:
                application/json:
                  example: !include json/UserPermissionResponse.example.json

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

  /{uuid}:
    get:
      is: [ include_role_perms ]
      description: Retrieves a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a single role with the given uuid.
      body:
        application/json:
          example: !include json/RoleUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    delete:
      description: Deletes a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

  /{uuid}/permissions/{pathToElement}:
    uriParameters:
      uuid:
        description: Uuid of the role that should be used to update the permissions.
        type: string
      pathToElement:
        description: Path to the element.
        example: |
            /:roleUuid/permissions/projects/:projectUuid/schemas/:schemaUuid
            /:roleUuid/permissions/projects/:projectUuid/schemas
            /:roleUuid/permissions/projects/:projectUuid/nodes
            /:roleUuid/permissions/projects/:projectUuid
            /:roleUuid/permissions/projects
        type: string
    get:
      description: |
        Return the role permission to the given element.
      responses:
        200:
          body:
            application/json:
              example: !include json/RolePermissionResponse.example.json
    put:
      description: |
        Update the role permission to the given element and update the permission to the given element. This is useful when it is required to grant certain permissions on a given path segment / object.
      body:
        application/json:
          example: !include json/RolePermissionRequest.example.json

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

  /{uuid}:
    is: [ localized, sortable ]
    get:
      description: Retrieves a single group with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GroupResponse.example.json
    put:
      description: Updates a single group with the given uuid.
      body:
        application/json:
          example: !include json/GroupUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/GroupResponse.example.json
    delete:
      description: Deletes a single group with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /roles:
      get:
        description: List all the roles for the given group.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/GroupListResponse.example.json
    /roles/{uuid}:
      put:
        description: Add the given role to the the group.
      delete:
        description: Remove the given role from the group.
        responses:
          200:
            body:
              application/json:
                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:
                example: !include json/GenericMessageResponse.example.json
      delete:
        description: Remove the user with the given uuid from the group.
        responses:
          200:
            body:
              application/json:
                example: !include json/GenericMessageResponse.example.json

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

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

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

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

#------------------------------------------------------------------------------
# Microschema Verticle
#------------------------------------------------------------------------------
/microschemas:
  is: [ localized ]
  displayName: Microschemas
  get:
    is: [ paged, include_role_perms ]
    description: Retrieves a list of microschemas.
    responses:
      200:
        body:
          application/json:
            example: !include json/MicroschemaListResponse.example.json
      400:
        description: Bad Request
      500:
        description: Internal Server Error
  post:
    description: Create the microschema.
    body:
      application/json:
        example: !include json/MicroschemaCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/MicroschemaResponse.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/MicroschemaResponse.example.json
    put:
      description: Updates the microschema with the given uuid.
      body:
        application/json:
          example: !include json/MicroschemaUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/MicroschemaResponse.example.json
    delete:
      description: Deletes the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

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

/{projectName}/webroot:
  is: [ localized, linkresolver ]
  displayName: WebRoot
  /{path}:
    is: [ localized, include_role_perms, imagehandler ]
    uriParameters:
      path:
        description: Path to a node.
        type: string
    get:
      description: Retrieves the node with the given path. Please note that it is also possible to query binary data instead of the node JSON metadata. Binary data will be returned if the targeted node provides a path segment using a binary field.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json

#------------------------------------------------------------------------------
# Node Verticle
#------------------------------------------------------------------------------
/{projectName}/nodes:
  displayName: Nodes
  /:
    get:
      is: [ localized, sortable, paged, expandable, include_role_perms ]
      description: Load all nodes.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeListResponse.example.json
    post:
      description: Create a new node.
      is: [ expandable, include_role_perms ]
      body:
        application/json:
          example: !include json/NodeCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
  /{uuid}:
    is: [ localized, linkresolver ]
    uriParameters:
      uuid:
        description: Uuid of a single node.
        type: string
    get:
      is: [ expandable, include_role_perms, translatable ]
      description: Retrieves the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
    put:
      is: [ expandable, include_role_perms ]
      description: Updates the node with the given uuid.
      body:
        application/json:
          example: !include json/NodeUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
        423:
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin:
      is: [ imagehandler ]
      get:
        description: Load the binary property value.
      put:
        description: Update the binary property value.
      post:
        description: Upload the binary property value.
    /tags:
      is: [ sortable, paged ]
      get:
        description: Load the tags that tag the node.
        responses:
          200:
            body:
              application/json:
                example: !include json/TagListResponse.example.json
    /tags/{tagUuuid}:
      put:
        description: Add the tag to the node.
      delete:
        description: Remove the tag from the node.
    /languages/{languageTag}:
      delete:
        description: Deletes the language from the given node.
        responses:
          200:
            body:
              application/json:
                example: !include json/GenericMessageResponse.example.json
    /children:
      get:
        is: [ localized, sortable, paged, expandable ]
        description: Load child nodes for the given node.
    /moveTo/{targetNodeUuid}:
      uriParameters:
        targetNodeUuid:
          description: Uuid of a the target node. This node will become the new parent of the source node.
          type: string
      put:
        description: Move the node to the given node.
    /breadcrumb:
      get:
        description: Return a breadcrumb for the given node.
        responses:
            200:
              body:
                application/json:
                  example: !include json/NodeBreadcrumbResponse.example.json
#------------------------------------------------------------------------------
# TagFamily Verticle
#------------------------------------------------------------------------------
/{projectName}/tagFamilies:
  displayName: TagFamilies
  uriParameters:
    projectName:
      description: Name of the project.
      type: string

  /:
    get:
      is: [ localized, sortable, paged, include_role_perms ]
      description: Load all tag families of the project.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagFamilyListResponse.example.json
    post:
      description: Create a new tag family.
      body:
        application/json:
          example: !include json/TagFamilyCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagFamilyResponse.example.json

  /{uuid}:
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag family.
        type: string
    get:
      is: [ localized, sortable, include_role_perms ]
      description: Load the tag family with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag family with the given path.
      body:
        application/json:
          example: !include json/TagFamilyUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagFamilyResponse.example.json
    delete:
      description: Delete the tag family with the given path.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /tags:
      get:
        description: Load all tags which were assigned to this tag family.
        responses:
          200:
            body:
              application/json:
                example: !include json/TagListResponse.example.json

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

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

  /{uuid}:
    is: [ include_role_perms ]
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable ]
      description: Load the tag with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag with the given path.
      body:
        application/json:
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the tag with the given path.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Search Verticle
#------------------------------------------------------------------------------
/search:
  displayName: Search
  /nodes:
    is: [ localized, paged ]
    displayName: Node Search
    post:
        description: Query for nodes. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        body:
            application/json:
        responses:
            200:
                body:
                    application/json:
                        example: !include json/NodeListResponse.example.json
  /tags:
    is: [ localized ]
    displayName: Tag Search
    post:
        description: Query for tags. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/TagListResponse.example.json
  /users:
    is: [ localized ]
    displayName: User Search
    post:
        description: Query for users. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/UserListResponse.example.json
  /groups:
    is: [ localized ]
    displayName: Group Search
    post:
        description: Query for groups. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/GroupListResponse.example.json
  /roles:
    is: [ localized ]
    displayName: Role Search
    post:
        description: Query for roles. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/RoleListResponse.example.json
  /projects:
    is: [ localized ]
    displayName: Project Search
    post:
        description: Query for projects. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/ProjectListResponse.example.json
  /tagFamilies:
    is: [ localized ]
    displayName: TagFamily Search
    post:
        description: Query for tagFamilies. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/TagFamilyListResponse.example.json
  /schemas:
    is: [ localized ]
    displayName: Schema Search
    post:
        description: Query for schemas. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/SchemaListResponse.example.json
  /microschemas:
    is: [ localized ]
    displayName: Microschema Search
    post:
        description: Query for microschemas. Accepts an elastic search json query. Please note that the from and size parameters can't be used because they conflict with the mesh paging parameters.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/MicroschemaListResponse.example.json
  /status:
   displayName: Search Status
   get:
     description: Load the search status information.
     responses:
            200:
                body:
                    application/json:
                        example: !include json/SearchStatusResponse.example.json

#------------------------------------------------------------------------------
# Authentication Verticle
#------------------------------------------------------------------------------
/auth:
  displayName: Authentication
  /me:
    get:
      description: Return the user response for the current user.
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json

  /login:
    post:
      description: Login the user using the provided credentials.
      body:
        application/json:
          example: !include json/LoginRequest.example.json
  /logout:
    get:
      description: Logout the user.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# Utility Verticle
#------------------------------------------------------------------------------
/utilities:
  displayName: Utilities
  /linkResolver:
    is: [ linkresolver ]
    post:
      queryParameters:
        project:
          description: Project for which the link resolving is done. This is important for invalid links.
          type: string
          default: project
      description: Resolve links in posted content. The content may be plain text, but also JSON.
      body:
        text/plain:
          example: Go to <a href="{{mesh.link('70bb205d44064671bb205d4406f671b3')}}">News</a>
      responses:
        200:
          body:
            text/plain:
              example: Go to <a href="/myproject/news/2016/news.html">News</a>


Add HEAD, OPTIONS methods to raml definition

#%RAML 0.8
---
title: Items API
documentation:
    - title: Items REST API
      content: |
        Welcome to the Items API.
baseUri: http://{host}:{port}/{version}
version: api
mediaType: application/json
protocols: [HTTP]

/items:
    displayName: Collection of items
    head:
        description: Head request
        responses:
            200:
                description: Return headers
    options:
        description: Options request
        responses:
            200:
                description: Return available HTTP methods
    get:
        description: Get all item
        responses:
            200:
                description: Returns a list of items
    post:
        description: Create a new item
        body:
            application/json:
                schema: !include items.json
                example: |
                    {
                        "id": "507f191e810c19729de860ea",
                        "name": "Banana",
                        "description": "Tasty"
                    }
        responses:
            201:
                description: Created item
                body:
                    application/json:
                        schema: !include items.json
    delete:
        description: Delete multiple items
        responses:
            200:
                description: Deleted multiple items
    patch:
        description: Update multiple items
        body:
            application/json:
                example: { "name": "Car" }
        responses:
            200:
                description: Updated multiple items
    put:
        description: Update multiple items
        body:
            application/json:
                example: { "name": "Plane" }
        responses:
            200:
                description: Updated multiple items

    /{id}:
        uriParameters:
            id:
                displayName: Item id
                type: string
                example: 507f191e810c19729de860ea
        displayName: Collection-item
        head:
            description: Head request
            responses:
                200:
                    description: Return headers
        options:
            description: Options request
            responses:
                200:
                    description: Return available HTTP methods
        get:
            description: Get a particular item
            responses:
                200:
                    body:
                        application/json:
                            schema: !include items.json

        delete:
            description: Delete a particular item
            responses:
                200:
                    description: Deleted item
        patch:
            description: Update a particular item
            body:
                application/json:
                    example: { "name": "Tree" }
            responses:
                200:
                    body:
                        application/json:
                            schema: !include items.json
        put:
            description: Replace a particular item
            body:
                application/json:
                    example: |
                        {
                            "id": "507f191e810c19729de860ea",
                            "name": "Horse",
                            "description": "Not tasty"
                        }
            responses:
                200:
                    body:
                        application/json:
                            schema: !include items.json

#%RAML 0.8
---
title: Items API
documentation:
    - title: Items REST API
      content: |
        Welcome to the Items API.
baseUri: http://{host}:{port}/{version}
version: api
mediaType: application/json
protocols: [HTTP]

/items:
    displayName: Collection of items
    get:
        description: Get all item
        responses:
            200:
                description: Returns a list of items
    post:
        description: Create a new item
        body:
            application/json:
                schema: !include items.json
                example: |
                    {
                        "id": "507f191e810c19729de860ea",
                        "name": "Banana",
                        "description": "Tasty"
                    }
        responses:
            201:
                description: Created item
                body:
                    application/json:
                        schema: !include items.json
    delete:
        description: Delete multiple items
        responses:
            200:
                description: Deleted multiple items
    patch:
        description: Update multiple items
        body:
            application/json:
                example: { "name": "Car" }
        responses:
            200:
                description: Updated multiple items
    put:
        description: Update multiple items
        body:
            application/json:
                example: { "name": "Plane" }
        responses:
            200:
                description: Updated multiple items

    /{id}:
        uriParameters:
            id:
                displayName: Item id
                type: string
                example: 507f191e810c19729de860ea
        displayName: Collection-item
        get:
            description: Get a particular item
            responses:
                200:
                    body:
                        application/json:
                            schema: !include items.json

        delete:
            description: Delete a particular item
            responses:
                200:
                    description: Deleted item
        patch:
            description: Update a particular item
            body:
                application/json:
                    example: { "name": "Tree" }
            responses:
                200:
                    body:
                        application/json:
                            schema: !include items.json
        put:
            description: Replace a particular item
            body:
                application/json:
                    example: |
                        {
                            "id": "507f191e810c19729de860ea",
                            "name": "Horse",
                            "description": "Not tasty"
                        }
            responses:
                200:
                    body:
                        application/json:
                            schema: !include items.json