Remove bogus 423 status codes

Remove bogus 423 status codes

#%RAML 0.8
title: preview-spec-core
version: 0.6.x
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:
  - recursively:
      queryParameters:
        maxDepth:
          description: Maximum depth for the navigation tree structure.
          default: 10
          type: number

  - 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. It is possible to specify multiple field names by separating with a ',' character.
          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/SchemaModel.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/SchemaModel.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/SchemaModel.example.json
    put:
      description: Invoke a schema migration.
      body:
        application/json:
          example: !include json/SchemaModel.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.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
  /{uuid}/diff:
    post:
      description: Create a diff of the latest and posted schema.
      responses:
        200:
          body:
            application/json:
              example: !include json/SchemaChangesListModel.example.json
  /{uuid}/changes:
    post:
      description: Invoke a schema migration.

#------------------------------------------------------------------------------
# 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/MicroschemaModel.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/MicroschemaModel.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/MicroschemaModel.example.json
    put:
      description: Invoke a microschema migration.
      body:
        application/json:
          example: !include json/MicroschemaModel.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Deletes the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
  /{uuid}/diff:
    post:
      description: Create a diff of the latest and posted microschema.
      responses:
        200:
          body:
            application/json:
              example: !include json/SchemaChangesListModel.example.json
  /{uuid}/changes:
    post:
      description: Invoke a microschema migration.

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

#------------------------------------------------------------------------------
# NavRoot Verticle
#------------------------------------------------------------------------------

/{projectName}/navroot:
  displayName: NavRoot
  /{path}:
    is: [ localized, include_role_perms, recursively, linkresolver ]
    uriParameters:
      path:
        description: Path to the navigation root node.
        type: string
    get:
      description: Load a nested navigation response using the given node as the root element of the navigation. Note that it is only possible to target container nodes.
      responses:
        200:
          body:
            application/json:
              example: !include json/NavigationResponse.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
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /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
      /fields/{fieldname}:
        get:
          is: [ imagehandler ]
          description: Load the binary property value.
        put:
          description: Update the binary property value.
        post:
          description: Upload the binary property value.
        /transform:
          post:
            description: Transform the binary property value (for binary fields)
            body:
              application/json:
                example: !include json/BinaryFieldTransformRequest.example.json
            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.
    /navigation:
      is: [ localized, recursively ]
      displayName: Navigation
      get:
        description: Return a nested navigation tree structure for the given node.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/NavigationResponse.example.json
    /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, translatable ]
    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

#------------------------------------------------------------------------------
# Eventbus Bridge Verticle
#------------------------------------------------------------------------------

/eventbus:
  displayName: Eventbus Bridge
  /:
    description: This endpoint is a SockJS compliant websocket that creates a bridge to the mesh eventbus. It allows handling of various mesh specific events.
  /websocket:
    description: Direct access to a websocket. This way the SockJS specific fallback is not used.

#------------------------------------------------------------------------------
# Admin Verticle
#------------------------------------------------------------------------------

/admin:
  displayName: Administration
  /migrationStatus:
    get:
      description: Fetch the current migration status.
      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: 0.6.x
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:
  - recursively:
      queryParameters:
        maxDepth:
          description: Maximum depth for the navigation tree structure.
          default: 10
          type: number

  - 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. It is possible to specify multiple field names by separating with a ',' character.
          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/SchemaModel.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/SchemaModel.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/SchemaModel.example.json
    put:
      description: Invoke a schema migration.
      body:
        application/json:
          example: !include json/SchemaModel.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.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
  /{uuid}/diff:
    post:
      description: Create a diff of the latest and posted schema.
      responses:
        200:
          body:
            application/json:
              example: !include json/SchemaChangesListModel.example.json
  /{uuid}/changes:
    post:
      description: Invoke a schema migration.

#------------------------------------------------------------------------------
# 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/MicroschemaModel.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/MicroschemaModel.example.json

  /{uuid}:
    is: [ localized ]
    get:
      description: Retrieves the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/MicroschemaModel.example.json
    put:
      description: Invoke a microschema migration.
      body:
        application/json:
          example: !include json/MicroschemaModel.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Deletes the microschema with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
  /{uuid}/diff:
    post:
      description: Create a diff of the latest and posted microschema.
      responses:
        200:
          body:
            application/json:
              example: !include json/SchemaChangesListModel.example.json
  /{uuid}/changes:
    post:
      description: Invoke a microschema migration.

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

#------------------------------------------------------------------------------
# NavRoot Verticle
#------------------------------------------------------------------------------

/{projectName}/navroot:
  displayName: NavRoot
  /{path}:
    is: [ localized, include_role_perms, recursively, linkresolver ]
    uriParameters:
      path:
        description: Path to the navigation root node.
        type: string
    get:
      description: Load a nested navigation response using the given node as the root element of the navigation. Note that it is only possible to target container nodes.
      responses:
        200:
          body:
            application/json:
              example: !include json/NavigationResponse.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:
    /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
      /fields/{fieldname}:
        get:
          is: [ imagehandler ]
          description: Load the binary property value.
        put:
          description: Update the binary property value.
        post:
          description: Upload the binary property value.
        /transform:
          post:
            description: Transform the binary property value (for binary fields)
            body:
              application/json:
                example: !include json/BinaryFieldTransformRequest.example.json
            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.
    /navigation:
      is: [ localized, recursively ]
      displayName: Navigation
      get:
        description: Return a nested navigation tree structure for the given node.
        responses:
            200:
                body:
                    application/json:
                        example: !include json/NavigationResponse.example.json
    /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, translatable ]
    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

#------------------------------------------------------------------------------
# Eventbus Bridge Verticle
#------------------------------------------------------------------------------

/eventbus:
  displayName: Eventbus Bridge
  /:
    description: This endpoint is a SockJS compliant websocket that creates a bridge to the mesh eventbus. It allows handling of various mesh specific events.
  /websocket:
    description: Direct access to a websocket. This way the SockJS specific fallback is not used.

#------------------------------------------------------------------------------
# Admin Verticle
#------------------------------------------------------------------------------

/admin:
  displayName: Administration
  /migrationStatus:
    get:
      description: Fetch the current migration status.
      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>


Neutron Shared IPs API doc updates

Neutron Shared IPs API doc updates

- Added query params for the /ip_addresses GET call
- Added query params for the /ip_addresses/{id}/ports GET call
- Added device_id in the GET /ip_addresses/{id}/ports response examples

#%RAML 0.8
title: Neutron Shared IPs API
version: v2.0
baseUri: https://{neutronUri}/{version}/
mediaType: application/json
traits:
    - secured:
        headers:
            X-Auth-Token:
                description: Token for request's tenant
                required: true
                type: string
/ip_addresses:
    displayName: Neutron IP Addresses
    description: A collection of IP addresses
    is: [ secured ]
    get:
        description: List all IPs for a given tenant
        queryParameters:
            # All from the IP addresses response
            id:
                description: filters by IP addresses UUID
                type: string
            network_id:
                description: filters IP addresses by their network UUID
                type: string
            address:
                description: filters IP address by their address
                type: string
            # Query will support only one port ID
            port_ids:
                description: filters IP addresses by a port UUID
                type: string
            subnet_id:
                description: filters IP addresses by their subnet UUID
                type: string
            tenant_id:
                description: filters IP addresses by their user tenant ID
                type: string
            version:
                description: filters IP addresses by their version 4 or 6
                type: int
            type:
                description: filters IP addresses by their type, for ex. fixed
                type: string

            # Plus the following /ip_addresses/{id}/ports child resources
            device_id:
                description: filters IP addresses by their ports' device_id
                type: string
            service:
                description: filters IP addresses by their service
                type: string
        responses:
            200:
                description: ok
                body:
                    application/json:
                        example: |
                            {"ip_addresses": [{
                                "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
                                "address": "192.168.10.1",
                                "port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
                                "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                "tenant_id": "2345678",
                                "version": "4",
                                "type": "fixed"}]}
    post:
        description: |
            Neutron creates an IP address on a specified network (network_id) with a specified IP version (version).
            A list of device_ids may be optionally specified to create the IP address and added to their respective ports.
            A list of port_ids may be optionally specified to create the IP address and added to the specified ports.
            At least one of device_ids or port_ids must be specified.
            Defaults all ports' service to "none".
        body:
            application/json:
                  example: |
                      {
                          "ip_address": {
                              "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
                              "version": 4,
                              "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"]}
                      }
        responses:
            201:
                description: created
                body:
                    application/json:
                        example: |
                            {
                                "ip_address": {
                                    "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                    "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
                                    "address": "192.168.10.1",
                                    "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"],
                                    "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                    "tenant_id": "2345678",
                                    "version": "4",
                                    "type": "fixed"}
                            }
            400:
                description: |
                    bad input
                    * IP version not 4 nor 6
                    * Ambiguous ports: multiple ports associated with a single device_id (devices with multiple ports must use the port_ids field)
            401:
                description: |
                    unauthorized
                    * Cannot create IP address on other tenant's network (can create IP address on provider network)
            404:
                description: |
                    Not found
                    * Network not found.
                    * Subnet with desired IP version not found.
                    * Ports not found.
    /{ipAddressId}:
        description: A specific IP address, a member of the IP addresses collection
        get:
            description: shows a specific IP address
            responses:
                200:
                    description: ok
                    body:
                        application/json:
                            example: |
                                {"ip_address": {
                                    "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                    "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
                                    "address": "192.168.10.1",
                                    "port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
                                    "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                    "tenant_id": "2345678",
                                    "version": "4",
                                    "type": "fixed"}
                404:
                    description: not found, e.g. another tenant's IP address
        put:
            description: |
                update an IP address, e.g. to change ports. This will eliminate any previous associations to ports.
            body:
                application/json:
                    example: |
                        {"ip_address": {
                            "port_ids": ['275b0516-206f-4421-8e42-1d3d1e4e9fb2', '66811c0a-fdbd-49d4-b1dd-f0f15a329744']}
            responses:
                200:
                    description: updated
                404:
                    description: |
                        not found
                        * attempting to update another tenant's IP address
                        * ports not found
        delete:
            description: delete an IP address
            responses:
                204:
                    description: deleted
                400:
                    description: |
                        bad request
                        * attempting to delete an IP with a `service != "none"` port (tenant should disassociate on nova-side first)
                        * attempting to delete a provider network's IP address
                404:
                    description: |
                        not found
                        * attempting to delete another tenant's IP address
        /ports/:
            description: |
                Collection of ports for a given IP address.
                This URI will be hidden to tenants.
            get:
                description: |
                    List the ports associated with an IP address
                queryParameters:
                    id:
                        description: filters ports for a specific ip_address_id by their UUID
                        type: string
                    device_id:
                        description: filter ports for a specific ip_address_id by their device_id
                        type: string
                    service:
                        description: filters ports for a specific ip_address_id by their service
                        type: string
                responses:
                    200:
                        description: ok
                        body:
                            application/json:
                                example: |
                                    {"ports": [{"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute",
                                    "device_id": "3b150725-cebb-492d-8286-9dbe80b54a87"}]}
                    404:
                        description: not found
            post:
                responses:
                    501:
                        description: not implemented
            /{portId}:
                get:
                    description: Shows a specific IP address service
                    body:
                        application/json:
                            example: |
                                {"port": {"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute",
                                "device_id": "3b150725-cebb-492d-8286-9dbe80b54a87"}}
                put:
                    description: |
                        Internal call from nova to neutron to update an IP address's service to either "none" or "compute"
                    body:
                        application/json:
                            example: |
                                {"port": {"service": "compute"}}
                    responses:
                        200:
                            description: updated
                        400:
                            description: |
                                bad input
                                * where another port for this given IP is active
                                * service string too long (max 256, for example)
                        401:
                            description: |
                                unauthorized, e.g. only nova can make this PUT
                        404:
                            description: |
                                not found, e.g.where this port_id=portId does not exist or belongs to other tenant
                delete:
                    responses:
                        501:
                            description: not implemented

#%RAML 0.8
title: Neutron Shared IPs API
version: v2.0
baseUri: https://{neutronUri}/{version}/
mediaType: application/json
traits:
    - secured:
        headers:
            X-Auth-Token:
                description: Token for request's tenant
                required: true
                type: string
/ip_addresses:
    displayName: Neutron IP Addresses
    description: A collection of IP addresses
    is: [ secured ]
    get:
        description: List all IPs for a given tenant
        queryParameters:  # This is not a complete list of query parameters, just the ones relevant to Shared IP.
            device_id:
                description: filters IP addresses by their ports' device_id
                type: string
            service:
                description: filters IP addresses by their service
                type: string
        responses:
            200:
                description: ok
                body:
                    application/json:
                        example: |
                            {"ip_addresses": [{
                                "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
                                "address": "192.168.10.1",
                                "port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
                                "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                "tenant_id": "2345678",
                                "version": "4",
                                "type": "fixed"}]}
    post:
        description: |
            Neutron creates an IP address on a specified network (network_id) with a specified IP version (version).
            A list of device_ids may be optionally specified to create the IP address and added to their respective ports.
            A list of port_ids may be optionally specified to create the IP address and added to the specified ports.
            At least one of device_ids or port_ids must be specified.
            Defaults all ports' service to "none".
        body:
            application/json:
                  example: |
                      {
                          "ip_address": {
                              "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
                              "version": 4,
                              "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"]}
                      }
        responses:
            201:
                description: created
                body:
                    application/json:
                        example: |
                            {
                                "ip_address": {
                                    "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                    "network_id": "fda61e0b-a410-49e8-ad3a-64c595618c7e",
                                    "address": "192.168.10.1",
                                    "port_ids": ["6200d533-a42b-4c04-82a1-cc14dbdbf2de"],
                                    "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                    "tenant_id": "2345678",
                                    "version": "4",
                                    "type": "fixed"}
                            }
            400:
                description: |
                    bad input
                    * IP version not 4 nor 6
                    * Ambiguous ports: multiple ports associated with a single device_id (devices with multiple ports must use the port_ids field)
            401:
                description: |
                    unauthorized
                    * Cannot create IP address on other tenant's network (can create IP address on provider network)
            404:
                description: |
                    Not found
                    * Network not found.
                    * Subnet with desired IP version not found.
                    * Ports not found.
    /{ipAddressId}:
        description: A specific IP address, a member of the IP addresses collection
        get:
            description: shows a specific IP address
            responses:
                200:
                    description: ok
                    body:
                        application/json:
                            example: |
                                {"ip_address": {
                                    "id": "4cacd68e-d7aa-4ff2-96f4-5c6f57dba737",
                                    "network_id": "6870304a-7212-443f-bd0c-089c886b44df",
                                    "address": "192.168.10.1",
                                    "port_ids": ['2f693cca-7383-45da-8bae-d26b6c2d6718'],
                                    "subnet_id": "f11687e8-ef0d-4207-8e22-c60e737e473b",
                                    "tenant_id": "2345678",
                                    "version": "4",
                                    "type": "fixed"}
                404:
                    description: not found, e.g. another tenant's IP address
        put:
            description: |
                update an IP address, e.g. to change ports. This will eliminate any previous associations to ports.
            body:
                application/json:
                    example: |
                        {"ip_address": {
                            "port_ids": ['275b0516-206f-4421-8e42-1d3d1e4e9fb2', '66811c0a-fdbd-49d4-b1dd-f0f15a329744']}
            responses:
                200:
                    description: updated
                404:
                    description: |
                        not found
                        * attempting to update another tenant's IP address
                        * ports not found
        delete:
            description: delete an IP address
            responses:
                204:
                    description: deleted
                400:
                    description: |
                        bad request
                        * attempting to delete an IP with a `service != "none"` port (tenant should disassociate on nova-side first)
                        * attempting to delete a provider network's IP address
                404:
                    description: |
                        not found
                        * attempting to delete another tenant's IP address
        /ports/:
            description: |
                Collection of ports for a given IP address.
                This URI will be hidden to tenants.
            get:
                description: |
                    List the ports associated with an IP address
                queryParameters:
                    device_id:
                        description: filter ports for a specific ip_address_id by their device_id
                        type: string
                responses:
                    200:
                        description: ok
                        body:
                            application/json:
                                example: |
                                    {"ports": [{"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute"}]}
                    404:
                        description: not found
            post:
                responses:
                    501:
                        description: not implemented
            /{portId}:
                get:
                    description: Shows a specific IP address service
                    body:
                        application/json:
                            example: |
                                {"port": {"id": "dce3dca6-2cba-4e00-95e9-748587f94620", "service": "compute"}}
                put:
                    description: |
                        Internal call from nova to neutron to update an IP address's service to either "none" or "compute"
                    body:
                        application/json:
                            example: |
                                {"port": {"service": "compute"}}
                    responses:
                        200:
                            description: updated
                        400:
                            description: |
                                bad input
                                * where another port for this given IP is active
                                * service string too long (max 256, for example)
                        401:
                            description: |
                                unauthorized, e.g. only nova can make this PUT
                        404:
                            description: |
                                not found, e.g.where this port_id=portId does not exist or belongs to other tenant
                delete:
                    responses:
                        501:
                            description: not implemented