Add missing raml endpoint

Add missing raml endpoint

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

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

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

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

  - paged:
      queryParameters:
        page:
          description: The page to be displayed. Please note that page numbering is 1-based and that omitting the page parameter will return the first page 1.
          type: number
        per_page:
          description: The page size. A page size of 25 will be used when this parameter is omitted.
          type: number

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

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

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

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

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

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

  - NodeResponse: !include json/NodeResponse.schema.json
  - NodeUpdateRequest: !include json/NodeUpdateRequest.schema.json
  - NodeCreateRequest: !include json/NodeCreateRequest.schema.json

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#------------------------------------------------------------------------------
# Node Verticle
#------------------------------------------------------------------------------
/{project_name}/nodes:
  displayName: Nodes
  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all nodes.
      responses:
        200:
          body:
            application/json:
              schema: NodeListResponse
              example: !include json/NodeListResponse.example.json
    post:
      description: Create a new node.
      body:
        application/json:
          schema: NodeCreateRequest
          example: !include json/NodeCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json
  /{uuid}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      uuid:
        description: Uuid of a single node.
        type: string
    get:
      description: Retrieves the node with the given uuid.
      queryParameters:
        lang:
          description: Filter the languages in the form of a list containing [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag) which are separated by comma.
          example: /{project_name}/nodes/?lang=de-DE,en-US
        update:
          description: The node will be locked when the *update* parameter is set to true.
          example: /{project_name}/nodes/?update=true
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json
    put:
      description: Updates the node with the given uuid.
      body:
        application/json:
          schema: NodeUpdateRequest
          example: !include json/NodeUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json
        423:
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin/{name}:
      get:
        description: Load the binary property value.
      put:
        description: Update the binary property value.
    /tags:
      get:
        description: Load the tags that tag the node.
    /children:
      get:
        description: Load child nodes for the given node.

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

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

  /{uuid}:
    is: [ perm_listable ]
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable, nested ]
      description: Load the tag with the given uuid.
      queryParameters:
        depth:
          description: Determines the depth of traversal for fetching nested tags.
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag with the given path.
      body:
        application/json:
          schema: TagUpdateRequest
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the tag with the given path.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /tags:
      get:
        description: Load all tags which were used for tagging.
      post:
        description: Tag the tag.
      delete:
        description: Untag the tag.
    /children:
      get:
        description: Load a list of children.
    /bin/{name}:
      get:
        description: Load the binary property value.
      put:
        description: Update the binary property value.

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

/{project_name}/webroot:
  is: [ localized ]
  displayName: WebRoot
  /{path}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      path:
        description: Path to a node.
        type: string
    get:
      description: Retrieves the node with the given path.
      queryParameters:
        lang:
          description: Filter the languages in the form of a list containing [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag) which are separated by comma.
          example: /{project_name}/nodes/?lang=de-DE,en-US
        update:
          description: The node will be locked when the *update* parameter is set to true.
          example: /{project_name}/nodes/?update=true
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json

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

/search:
  is: [ localized ]
  displayName: Global Search
  get:
    description: Query for various objects.

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

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

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

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

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

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

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

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

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

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

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

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

  - paged:
      queryParameters:
        page:
          description: The page to be displayed. Please note that page numbering is 1-based and that omitting the page parameter will return the first page 1.
          type: number
        per_page:
          description: The page size. A page size of 25 will be used when this parameter is omitted.
          type: number

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

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

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

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

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

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

  - NodeResponse: !include json/NodeResponse.schema.json
  - NodeUpdateRequest: !include json/NodeUpdateRequest.schema.json
  - NodeCreateRequest: !include json/NodeCreateRequest.schema.json

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#------------------------------------------------------------------------------
# Node Verticle
#------------------------------------------------------------------------------
/{project_name}/nodes:
  displayName: Nodes
  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all nodes.
      responses:
        200:
          body:
            application/json:
              schema: NodeListResponse
              example: !include json/NodeListResponse.example.json
    post:
      description: Create a new node.
      body:
        application/json:
          schema: NodeCreateRequest
          example: !include json/NodeCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json
  /{uuid}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      uuid:
        description: Uuid of a single node.
        type: string
    get:
      description: Retrieves the node with the given uuid.
      queryParameters:
        lang:
          description: Filter the languages in the form of a list containing [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag) which are separated by comma.
          example: /{project_name}/nodes/?lang=de-DE,en-US
        update:
          description: The node will be locked when the *update* parameter is set to true.
          example: /{project_name}/nodes/?update=true
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json
    put:
      description: Updates the node with the given uuid.
      body:
        application/json:
          schema: NodeUpdateRequest
          example: !include json/NodeUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json
        423:
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin/{name}:
      get:
        description: Load the binary property value.
      put:
        description: Update the binary property value.
    /tags:
      get:
        description: Load the tags that tag the node.

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

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

  /{uuid}:
    is: [ perm_listable ]
    uriParameters:
      uuid:
        description: |
             The uuid of a single tag.
        type: string
    get:
      is: [ localized, sortable, nested ]
      description: Load the tag with the given uuid.
      queryParameters:
        depth:
          description: Determines the depth of traversal for fetching nested tags.
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag with the given path.
      body:
        application/json:
          schema: TagUpdateRequest
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              schema: TagResponse
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the tag with the given path.
      responses:
        200:
          body:
            application/json:
              schema: GenericMessageResponse
              example: !include json/GenericMessageResponse.example.json
    /tags:
      get:
        description: Load all tags which were used for tagging.
      post:
        description: Tag the tag.
      delete:
        description: Untag the tag.
    /children:
      get:
        description: Load a list of children.
    /bin/{name}:
      get:
        description: Load the binary property value.
      put:
        description: Update the binary property value.

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

/{project_name}/webroot:
  is: [ localized ]
  displayName: WebRoot
  /{path}:
    is: [ localized, sortable, nested, perm_listable ]
    uriParameters:
      path:
        description: Path to a node.
        type: string
    get:
      description: Retrieves the node with the given path.
      queryParameters:
        lang:
          description: Filter the languages in the form of a list containing [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag) which are separated by comma.
          example: /{project_name}/nodes/?lang=de-DE,en-US
        update:
          description: The node will be locked when the *update* parameter is set to true.
          example: /{project_name}/nodes/?update=true
      responses:
        200:
          body:
            application/json:
              schema: NodeResponse
              example: !include json/NodeResponse.example.json

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

/search:
  is: [ localized ]
  displayName: Global Search
  get:
    description: Query for various objects.

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

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

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

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

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

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

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

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


and back to mybring again

and back to mybring again

#%RAML 0.8
---
title: Reports API
baseUri: https://www.mybring.com/reports/api

documentation:
- title: Introduction
  content: |
    The Reports API is used to generate shipment reports, the same set of reports that are available in mybring.

    Each Mybring user is associated with a set of customers and has access to specific set of report types for which they can generate a report.

    The following steps (which will be API calls) enables you to generate a report:

    1. Get the customers associated with the mybring user.
    2. Get the report types allowed for a customer.
    3. Initiate report creation and get report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
    4. After initiating report creation, you can check the status if the job. I.e. if it is in progress, completed or failed. When status is completed, a URL for fetching the actual report is returned.
    5. The report can then be downloaded.

    For all the above APIs we need to identify and authenticate the user. This is done by passing the following header information. These are described in Reference section:

    - Mybring username (email address)
    - API Key

    All these APIs are available in json and xml formats.

- title: How to use
  content: |
    The Reports API is a logged-in service and you need to get an API-key and authenticate before being able to use the API.

    The two first steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

    1. Get customer IDs
    2. Get list of available reports
    3. Generate report
    4. Check status of report
    5. Download report
    6. Get list of invoice numbers for given customer or group

- title: Authentication
  content: |
    The Reports API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/generate{mediaTypeExtension}:
  displayName: List available customers
  description: |
    List available customers for the provided API credentials.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available customers
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_customers.json
          application/xml:
            example: !include examples/list_customers.xml

/generate/{customerId}{mediaTypeExtension}:
  displayName: List available reports for a customer
  description: |
    Each customer has a set of reports available. This endpoint lists all available reports for a given customer.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available reports for a customer
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_reports.json
          application/xml:
            example: !include examples/list_reports.xml

/generate/{customerId}/{reportTypeId}{mediaTypeExtension}:
  displayName: Generate a report
  description: |
    To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.

    This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.

    The example below shows how to generate a PARCELS-DELIVERED report for PARCELS_NORWAY-00012341234 in the period 01.07.2014 to 01.08.2014.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    reportTypeId:
      description: A report type ID from the 'list of available reports' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Generate a report
    queryParameters:
      parameterName:
        description: The different report types have different params. The params are doucmented in the list of available reports, for example `fromDate` and `toDate`.
        type: string
        required: true
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      202:
        displayName: Successful response
        headers:
          Location:
            description: URL to get status of the generated report
            required: true
            type: string
            example: https://www.mybring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/
        body:
          application/json:
            example: !include examples/generate_report.json
          application/xml:
            example: !include examples/generate_report.xml

/reports/{reportId}/status{mediaTypeExtension}:
  displayName: Check the status of a report
  description: |
    Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display `NOT_DONE`, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Check the status of a report
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report status
        description: Examples show different statuses.
        body:
          application/json+notdone:
            example: !include examples/status_not_done.json
          application/json+done:
            example: !include examples/status_done.json
          application/json+failed:
            example: !include examples/status_failed.json
          application/xml+notdone:
            example: !include examples/status_not_done.xml
          application/xml+done:
            example: !include examples/status_done.xml
          application/xml+failed:
            example: !include examples/status_failed.xml

/reports/{reportId}{mediaTypeExtension}:
  displayName: Get report
  description: |
    Returns the generated report.
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .xls, .xml ]
      description: Use .xls to get Excel file or .xml to get XML file.
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report
        description: Examples show different statuses.
        body:
          application/xml:
            example: !include examples/empty_report.xml

/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List invoice numbers
  description: |
    Get the list of invoice numbers for a customer id or a customer group.
  uriParameters:
    customerOrGroupId:
      description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_invoices.json
          application/xml:
            example: !include examples/list_invoices.xml

#%RAML 0.8
---
title: Reports API
baseUri: https://api.bring.com/reports/api

documentation:
- title: Introduction
  content: |
    The Reports API is used to generate shipment reports, the same set of reports that are available in mybring.

    Each Mybring user is associated with a set of customers and has access to specific set of report types for which they can generate a report.

    The following steps (which will be API calls) enables you to generate a report:

    1. Get the customers associated with the mybring user.
    2. Get the report types allowed for a customer.
    3. Initiate report creation and get report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
    4. After initiating report creation, you can check the status if the job. I.e. if it is in progress, completed or failed. When status is completed, a URL for fetching the actual report is returned.
    5. The report can then be downloaded.

    For all the above APIs we need to identify and authenticate the user. This is done by passing the following header information. These are described in Reference section:

    - Mybring username (email address)
    - API Key

    All these APIs are available in json and xml formats.

- title: How to use
  content: |
    The Reports API is a logged-in service and you need to get an API-key and authenticate before being able to use the API.

    The two first steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

    1. Get customer IDs
    2. Get list of available reports
    3. Generate report
    4. Check status of report
    5. Download report
    6. Get list of invoice numbers for given customer or group

- title: Authentication
  content: |
    The Reports API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/generate{mediaTypeExtension}:
  displayName: List available customers
  description: |
    List available customers for the provided API credentials.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available customers
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_customers.json
          application/xml:
            example: !include examples/list_customers.xml

/generate/{customerId}{mediaTypeExtension}:
  displayName: List available reports for a customer
  description: |
    Each customer has a set of reports available. This endpoint lists all available reports for a given customer.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available reports for a customer
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_reports.json
          application/xml:
            example: !include examples/list_reports.xml

/generate/{customerId}/{reportTypeId}{mediaTypeExtension}:
  displayName: Generate a report
  description: |
    To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.

    This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.

    The example below shows how to generate a PARCELS-DELIVERED report for PARCELS_NORWAY-00012341234 in the period 01.07.2014 to 01.08.2014.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    reportTypeId:
      description: A report type ID from the 'list of available reports' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Generate a report
    queryParameters:
      parameterName:
        description: The different report types have different params. The params are doucmented in the list of available reports, for example `fromDate` and `toDate`.
        type: string
        required: true
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      202:
        displayName: Successful response
        headers:
          Location:
            description: URL to get status of the generated report
            required: true
            type: string
            example: https://www.mybring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/
        body:
          application/json:
            example: !include examples/generate_report.json
          application/xml:
            example: !include examples/generate_report.xml

/reports/{reportId}/status{mediaTypeExtension}:
  displayName: Check the status of a report
  description: |
    Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display `NOT_DONE`, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Check the status of a report
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report status
        description: Examples show different statuses.
        body:
          application/json+notdone:
            example: !include examples/status_not_done.json
          application/json+done:
            example: !include examples/status_done.json
          application/json+failed:
            example: !include examples/status_failed.json
          application/xml+notdone:
            example: !include examples/status_not_done.xml
          application/xml+done:
            example: !include examples/status_done.xml
          application/xml+failed:
            example: !include examples/status_failed.xml

/reports/{reportId}{mediaTypeExtension}:
  displayName: Get report
  description: |
    Returns the generated report.
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .xls, .xml ]
      description: Use .xls to get Excel file or .xml to get XML file.
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report
        description: Examples show different statuses.
        body:
          application/xml:
            example: !include examples/empty_report.xml

/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List invoice numbers
  description: |
    Get the list of invoice numbers for a customer id or a customer group.
  uriParameters:
    customerOrGroupId:
      description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_invoices.json
          application/xml:
            example: !include examples/list_invoices.xml


Remove old link to auth from reports

Remove old link to auth from reports

#%RAML 0.8
---
title: Reports API
baseUri: https://api.bring.com/reports/api

documentation:
- title: Introduction
  content: |
    The Reports API is used to generate shipment reports, the same set of reports that are available in mybring.

    Each Mybring user is associated with a set of customers and has access to specific set of report types for which they can generate a report.

    The following steps (which will be API calls) enables you to generate a report:

    1. Get the customers associated with the mybring user.
    2. Get the report types allowed for a customer.
    3. Initiate report creation and get report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
    4. After initiating report creation, you can check the status if the job. I.e. if it is in progress, completed or failed. When status is completed, a URL for fetching the actual report is returned.
    5. The report can then be downloaded.

    For all the above APIs we need to identify and authenticate the user. This is done by passing the following header information. These are described in Reference section:

    - Mybring username (email address)
    - API Key

    All these APIs are available in json and xml formats.

- title: How to use
  content: |
    The Reports API is a logged-in service and you need to get an API-key and authenticate before being able to use the API.

    The two first steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

    1. Get customer IDs
    2. Get list of available reports
    3. Generate report
    4. Check status of report
    5. Download report
    6. Get list of invoice numbers for given customer or group

- title: Authentication
  content: |
    The Reports API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/generate{mediaTypeExtension}:
  displayName: List available customers
  description: |
    List available customers for the provided API credentials.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available customers
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_customers.json
          application/xml:
            example: !include examples/list_customers.xml

/generate/{customerId}{mediaTypeExtension}:
  displayName: List available reports for a customer
  description: |
    Each customer has a set of reports available. This endpoint lists all available reports for a given customer.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available reports for a customer
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_reports.json
          application/xml:
            example: !include examples/list_reports.xml

/generate/{customerId}/{reportTypeId}{mediaTypeExtension}:
  displayName: Generate a report
  description: |
    To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.

    This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.

    The example below shows how to generate a PARCELS-DELIVERED report for PARCELS_NORWAY-00012341234 in the period 01.07.2014 to 01.08.2014.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    reportTypeId:
      description: A report type ID from the 'list of available reports' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Generate a report
    queryParameters:
      parameterName:
        description: The different report types have different params. The params are doucmented in the list of available reports, for example `fromDate` and `toDate`.
        type: string
        required: true
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      202:
        displayName: Successful response
        headers:
          Location:
            description: URL to get status of the generated report
            required: true
            type: string
            example: https://api.bring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/
        body:
          application/json:
            example: !include examples/generate_report.json
          application/xml:
            example: !include examples/generate_report.xml

/reports/{reportId}/status{mediaTypeExtension}:
  displayName: Check the status of a report
  description: |
    Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display `NOT_DONE`, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Check the status of a report
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report status
        description: Examples show different statuses.
        body:
          application/json+notdone:
            example: !include examples/status_not_done.json
          application/json+done:
            example: !include examples/status_done.json
          application/json+failed:
            example: !include examples/status_failed.json
          application/xml+notdone:
            example: !include examples/status_not_done.xml
          application/xml+done:
            example: !include examples/status_done.xml
          application/xml+failed:
            example: !include examples/status_failed.xml

/reports/{reportId}{mediaTypeExtension}:
  displayName: Get report
  description: |
    Returns the generated report.
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .xls, .xml ]
      description: Use .xls to get Excel file or .xml to get XML file.
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report
        description: Examples show different statuses.
        body:
          application/xml:
            example: !include examples/empty_report.xml

/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List invoice numbers
  description: |
    Get the list of invoice numbers for a customer id or a customer group.
  uriParameters:
    customerOrGroupId:
      description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_invoices.json
          application/xml:
            example: !include examples/list_invoices.xml

#%RAML 0.8
---
title: Reports API
baseUri: https://api.bring.com/reports/api

documentation:
- title: Introduction
  content: |
    The Reports API is used to generate shipment reports, the same set of reports that are available in mybring.

    Each Mybring user is associated with a set of customers and has access to specific set of report types for which they can generate a report.

    The following steps (which will be API calls) enables you to generate a report:

    1. Get the customers associated with the mybring user.
    2. Get the report types allowed for a customer.
    3. Initiate report creation and get report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
    4. After initiating report creation, you can check the status if the job. I.e. if it is in progress, completed or failed. When status is completed, a URL for fetching the actual report is returned.
    5. The report can then be downloaded.

    For all the above APIs we need to identify and authenticate the user. This is done by passing the following header information. These are described in Reference section:

    - Mybring username (email address)
    - API Key

    All these APIs are available in json and xml formats.

- title: How to use
  content: |
    The Reports API is a logged-in service and you need to get an API-key and authenticate before being able to use the API. Read more about [how to get an API-key](http://developer.bring.com/additionalresources/getting-api-keys.html?from=reports), and how to use it for authentication.

    The two first steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

    1. Get customer IDs
    2. Get list of available reports
    3. Generate report
    4. Check status of report
    5. Download report
    6. Get list of invoice numbers for given customer or group

- title: Authentication
  content: |
    The Reports API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/generate{mediaTypeExtension}:
  displayName: List available customers
  description: |
    List available customers for the provided API credentials.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available customers
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_customers.json
          application/xml:
            example: !include examples/list_customers.xml

/generate/{customerId}{mediaTypeExtension}:
  displayName: List available reports for a customer
  description: |
    Each customer has a set of reports available. This endpoint lists all available reports for a given customer.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available reports for a customer
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_reports.json
          application/xml:
            example: !include examples/list_reports.xml

/generate/{customerId}/{reportTypeId}{mediaTypeExtension}:
  displayName: Generate a report
  description: |
    To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.

    This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.

    The example below shows how to generate a PARCELS-DELIVERED report for PARCELS_NORWAY-00012341234 in the period 01.07.2014 to 01.08.2014.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    reportTypeId:
      description: A report type ID from the 'list of available reports' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Generate a report
    queryParameters:
      parameterName:
        description: The different report types have different params. The params are doucmented in the list of available reports, for example `fromDate` and `toDate`.
        type: string
        required: true
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      202:
        displayName: Successful response
        headers:
          Location:
            description: URL to get status of the generated report
            required: true
            type: string
            example: https://api.bring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/
        body:
          application/json:
            example: !include examples/generate_report.json
          application/xml:
            example: !include examples/generate_report.xml

/reports/{reportId}/status{mediaTypeExtension}:
  displayName: Check the status of a report
  description: |
    Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display `NOT_DONE`, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Check the status of a report
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report status
        description: Examples show different statuses.
        body:
          application/json+notdone:
            example: !include examples/status_not_done.json
          application/json+done:
            example: !include examples/status_done.json
          application/json+failed:
            example: !include examples/status_failed.json
          application/xml+notdone:
            example: !include examples/status_not_done.xml
          application/xml+done:
            example: !include examples/status_done.xml
          application/xml+failed:
            example: !include examples/status_failed.xml

/reports/{reportId}{mediaTypeExtension}:
  displayName: Get report
  description: |
    Returns the generated report.
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .xls, .xml ]
      description: Use .xls to get Excel file or .xml to get XML file.
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report
        description: Examples show different statuses.
        body:
          application/xml:
            example: !include examples/empty_report.xml

/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List invoice numbers
  description: |
    Get the list of invoice numbers for a customer id or a customer group.
  uriParameters:
    customerOrGroupId:
      description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_invoices.json
          application/xml:
            example: !include examples/list_invoices.xml