Remove depth parameter

Remove depth parameter

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

#------------------------------------------------------------------------------
# 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:
            example: !include json/UserListResponse.example.json

  post:
    description: Create new user.
    body:
      application/json:
        example: !include json/UserCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            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:
              example: !include json/UserResponse.example.json
    put:
      description: Updates the user with the given uuid.
      body:
          application/json:
              example: !include json/UserUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json
    delete:
      description: Deletes the user with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

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

  /{uuid}:
    get:
      is: [ perm_listable ]
      description: Retrieves a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a single role with the given uuid.
      body:
        application/json:
          example: !include json/RoleUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    delete:
      description: Deletes a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /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 ]
  displayName: Groups
  get:
    is: [ paged, searchable, perm_listable ]
    description: Retrieves a list of groups.
    responses:
      200:
        body:
          application/json:
            example: !include json/GroupListResponse.example.json
  post:
    description: Create a new group.
    body:
        application/json:
            example: !include json/GroupCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/GroupResponse.example.json

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

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

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

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

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

#------------------------------------------------------------------------------
# Node Verticle
#------------------------------------------------------------------------------
/{project_name}/nodes:
  displayName: Nodes
  /:
    get:
      is: [ localized, sortable, paged ]
      description: Load all nodes.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeListResponse.example.json
    post:
      description: Create a new node.
      body:
        application/json:
          example: !include json/NodeCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
  /{uuid}:
    is: [ localized, sortable, 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:
              example: !include json/NodeResponse.example.json
    put:
      description: Updates the node with the given uuid.
      body:
        application/json:
          example: !include json/NodeUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
        423:
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin/{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.

#------------------------------------------------------------------------------
# TagFamily Verticle
#------------------------------------------------------------------------------
/{project_name}/tagFamilies:
  displayName: TagFamilies
  uriParameters:
    project_name:
      description: Name of the project.
      type: string

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

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

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

  /:
    get:
      is: [ localized, sortable, 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:
          example: !include json/TagCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              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 ]
      description: Load the tag with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag with the given path.
      body:
        application/json:
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the tag with the given path.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

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

/{project_name}/webroot:
  is: [ localized ]
  displayName: WebRoot
  /{path}:
    is: [ localized, sortable, 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:
              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:
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a previouly deployed vertx maven server.
      responses:
        200:
          body:
            application/json:
              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:
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a verticle with the given class.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

  /backup:
    is: [ localized ]
    get:
      description: Invoke the live backup process.
      responses:
        200:
          body:
            application/json:
              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

#------------------------------------------------------------------------------
# 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:
            example: !include json/UserListResponse.example.json

  post:
    description: Create new user.
    body:
      application/json:
        example: !include json/UserCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            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:
              example: !include json/UserResponse.example.json
    put:
      description: Updates the user with the given uuid.
      body:
          application/json:
              example: !include json/UserUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/UserResponse.example.json
    delete:
      description: Deletes the user with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

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

  /{uuid}:
    get:
      is: [ perm_listable ]
      description: Retrieves a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    put:
      description: Updates a single role with the given uuid.
      body:
        application/json:
          example: !include json/RoleUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/RoleResponse.example.json
    delete:
      description: Deletes a single role with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
    /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:
            example: !include json/GroupListResponse.example.json
  post:
    description: Create a new group.
    body:
        application/json:
            example: !include json/GroupCreateRequest.example.json
    responses:
      200:
        body:
          application/json:
            example: !include json/GroupResponse.example.json

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

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

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

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

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

#------------------------------------------------------------------------------
# Node Verticle
#------------------------------------------------------------------------------
/{project_name}/nodes:
  displayName: Nodes
  /:
    get:
      is: [ localized, sortable, nested, paged ]
      description: Load all nodes.
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeListResponse.example.json
    post:
      description: Create a new node.
      body:
        application/json:
          example: !include json/NodeCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              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:
              example: !include json/NodeResponse.example.json
    put:
      description: Updates the node with the given uuid.
      body:
        application/json:
          example: !include json/NodeUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/NodeResponse.example.json
        423:
    delete:
      description: Deletes the node with the given uuid.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json
        423:
    /bin/{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.

#------------------------------------------------------------------------------
# TagFamily Verticle
#------------------------------------------------------------------------------
/{project_name}/tagFamilies:
  displayName: TagFamilies
  uriParameters:
    project_name:
      description: Name of the project.
      type: string

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

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

#------------------------------------------------------------------------------
# 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:
          example: !include json/TagCreateRequest.example.json
      responses:
        200:
          body:
            application/json:
              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.
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    put:
      description: Update the tag with the given path.
      body:
        application/json:
          example: !include json/TagUpdateRequest.example.json
      responses:
        200:
          body:
            application/json:
              example: !include json/TagResponse.example.json
    delete:
      description: Delete the tag with the given path.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

#------------------------------------------------------------------------------
# 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:
              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:
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a previouly deployed vertx maven server.
      responses:
        200:
          body:
            application/json:
              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:
              example: !include json/GenericMessageResponse.example.json
    delete:
      description: Undeploy a verticle with the given class.
      responses:
        200:
          body:
            application/json:
              example: !include json/GenericMessageResponse.example.json

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


example evidence resource body

example evidence resource body

#%RAML 0.8
title: OpenBEL API
version: 0.0.2
baseUri: http://next.belframework.org
schemas:
  - evidence: !include http://next.belframework.org/schema/evidence.schema.json
/api:
  description: The root resource collection.
  get:
    headers:
        Accept:
          displayName: Accept
    responses:
      200:
        body:
          application/hal+json:
            example: |
              {
                "_links": {
                  "item": [
                    {
                      "href": "http://next.belframework.org/api/annotations"
                    },
                    {
                      "href": "http://next.belframework.org/api/evidence"
                    },
                    {
                      "href": "http://next.belframework.org/api/expressions"
                    },
                    {
                      "href": "http://next.belframework.org/api/functions"
                    },
                    {
                      "href": "http://next.belframework.org/api/namespaces"
                    }
                  ]
                }
              }
  /annotations:
    description: Represents the annotation resource collection.
    get:
      description: Retrieves all annotation resources.
    /{annotation}:
      description: Represents a single annotation resource.
      get:
        description: Retrieves an annotation resource.
      /{annotation}/values:
        description: Represents all annotation value resources available on the annotation resource identified by *{annotation}*.
        /{value}:
          description: Represents a single annotation value resources available on the annotation resource identified by *{annotation}* and *{value}*.
          get:
            description:
  /evidence:
    description: |
      Operate on the evidence resource collection.

      *Operations*

      - Filter the evidence resource collection using `GET /evidence` with query parameters.
      - Retrieve an evidence resource using `GET /evidence/{id}`.
      - Create a new evidence resource using `POST /evidence` with a supported content type.
      - Update an existing evidence resource using `PUT /evidence/{id}` with a supported content type.
      - Delete an existing evidence resource using `DELETE /evidence/{id}`.

    post:
      description: |
        Create an evidence resource.

        Include a *profile* parameter in the *Content-Type* header to convey the schema evidence schema for the JSON document.

        *Example*:

        - `Content-Type: application/json; profile=http://next.belframework.org/schema/evidence.schema.json`
      responses:
        201:
          description: |
            *201 Created*

            The evidence resource was created.

            The link to the evidence resource is conveyed is the *Link* header.
        415:
          description: |
            *415 Unsupported Media Type*

            The evidence resource body was not a supported media type..
      body:
        application/json:
          schema: evidence
          example: |
            {
              "evidence": {
                "bel_statement": "a(CHEBI:\"reactive oxygen species\") increases r(HGNC:JUN)",
                "citation": {
                  "type": "PubMed",
                  "name": "Free Radic Biol Med 2000 Feb 1 28(3) 463-99",
                  "id": "10699758"
                },
                "biological_context": {
                  "Species": "9606",
                  "CellLine": "LNCAP cell",
                  "Anatomy": "prostate gland",
                  "Cell": "fibroblast",
                  "Disease": "leukemia"
                },
                "metadata": {
                  "status": "Approved"
                }
              }
            }
    get:
      description: |
        Retrieve the evidence resource collection.

        This collection must be paged using *offset* (defaults to `0`) as the start index and *length* (defaults to `100`) as the number of evidence resources to return.

        This collection can be filtered by specifying one or more *filter* query parameters. A filter query parameter specifies the *category*, *name*, and *value* of the filter and is encoded as a JSON object. For example the citation id filter might be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101"
          }
        ```

        This collection includes a *facets* array where each facet value is captured individually. For example for the citation id filter the facet object would be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101",
            "filter": "{\"category\": \"citation\", \"name\": \"id\", \"value\": \"133785101\"}",
            "count": 25
          }
        ```

        The *filter* property value has the same form as the *filter* query parameter. This is intended to support filtering the evidence resource collection by selected facets.
      headers:
        Accept:
          displayName: Accept
          description: |
            The Accept header informs the server which media types the client accepts.
      queryParameters:
        offset:
          type: integer
          description: The evidence resource index that starts a page of the evidence resource collection.
          example: 0
          required: false
        length:
          type: integer
          description: The length of the evidence resource collection to retrieve.
          example: 100
          required: false
        filter:
          type: string
          description: A filter to apply to the evidence resource collection to narrow the resources retrieved.
          example: |
            {"category":"context","name":"Anatomy","value":"prostate gland"}
          required: false
      responses:
        200:
          description: |
            An example path for this resource might be `http://next.belframework.org/api/evidence?offset=0&length=1&filter={%22category%22:%22context%22,%22name%22:%22Anatomy%22,%22value%22:%22prostate%20gland%22}`.
          body:
            application/json:
              example: |
                {
                  "_embedded": {
                    "evidence": [
                      {
                        "bel_statement": "p(HGNC:CDH1) decreases cat(complex(p(HGNC:ITGAV),p(HGNC:ITGB5)))",
                        "citation": {
                          "type": "Other",
                          "name": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer",
                          "id": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer"
                        },
                        "biological_context": {
                          "Species": "9606"
                        },
                        "metadata": {
                          "status": "Review"
                        }
                      }
                    ]
                  },
                  "facets": [
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "9606",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"9606\"}",
                      "count": 49071
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10090",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10090\"}",
                      "count": 19416
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Review",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Review\"}",
                      "count": 18954
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Approved",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Approved\"}",
                      "count": 18947
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Rejected",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Rejected\"}",
                      "count": 18896
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Draft",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Draft\"}",
                      "count": 18784
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10116",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10116\"}",
                      "count": 7091
                    },
                    {
                      "category": "context",
                      "name": "Anatomy",
                      "value": "liver",
                      "filter": "{\"category\":\"context\",\"name\":\"Anatomy\",\"value\":\"liver\"}",
                      "count": 2357
                    }
                  ]
                }
    /{identifier}:
      description:
      get:
      put:
        description: |
          Replaces an evidence resource identified by *{identifier}*.

          Include a *profile* parameter in the *Content-Type* header to convey the schema evidence schema for the JSON document.

          *Example*:

          - `Content-Type: application/json; profile=http://next.belframework.org/schema/evidence.schema.json`
        body:
          application/json:
            schema: evidence
            example: |
              {
                "evidence": {
                  "bel_statement": "a(CHEBI:\"reactive oxygen species\") increases r(HGNC:JUN)",
                  "citation": {
                    "type": "PubMed",
                    "name": "Free Radic Biol Med 2000 Feb 1 28(3) 463-99",
                    "id": "10699758"
                  },
                  "biological_context": {
                    "Species": "9606",
                    "CellLine": "LNCAP cell",
                    "Anatomy": "prostate gland",
                    "Cell": "fibroblast",
                    "Disease": "leukemia"
                  },
                  "metadata": {
                    "status": "Approved"
                  }
                }
              }
        responses:
          202:
            description: |
              *202 Accepted*

              The replacement for the evidence resource will be applied.
          404:
            description: |
              *404 Not Found*

              An evidence resource, identified by *{identifier}*, does not exist.
          415:
            description: |
              *415 Unsupported Media Type*

              The evidence resource body was not a supported media type.
      patch:
      delete:
  /expressions/{bel}/completions:
    description: |
      Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

      Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

      Custom Caret Position:

      The caret position can be provided to indicate where to complete from.

      Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
    uriParameters:
      bel:
        type: string
        description: BEL statement fragment; Completions will be provided for this input.
        required: false
    get:
      description: |
        Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

        Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

        Custom Caret Position:

        The caret position can be provided to indicate where to complete from.

        Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
      headers:
        Accept:
          displayName: Accept
      queryParameters:
        caret_position:
          type: integer
          description: The position of the caret within the *bel* input. Defaults to the right-most caret_position for *bel* (e.g. length of *bel* input).
          example: 0
          required: false
      responses:
        200:
          body:
            application/json:
              example: |
                [
                  {
                    "completion": {
                      "type": "namespace_prefix",
                      "label": "HGNC",
                      "value": "HGNC:",
                      "highlight": {
                        "start_position": 2,
                        "end_position": 3,
                        "range_type": "inclusive"
                      },
                      "actions": [
                        {
                          "delete": {
                              "start_position": 2,
                              "end_position": 3,
                              "range_type": "inclusive"
                          },
                          "insert": {
                              "position": 2,
                              "value": "HGNC:"
                          },
                          "move_cursor": {
                              "position": 7
                          }
                        }
                      ]
                    }
                  }
                ]
              schema: |
                {
                  "$schema": "http://json-schema.org/draft-04/schema",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "completion"
                    ],
                    "properties": {
                      "completion": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "type",
                          "label",
                          "value",
                          "highlight",
                          "actions"
                        ],
                        "properties": {
                          "type": {
                            "enum": [
                              "function",
                              "namespace_prefix",
                              "namespace_value"
                            ]
                          },
                          "label": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          },
                          "highlight": {
                            "oneOf": [
                              {
                                "type": "null"
                              },
                              {
                                "type": "object",
                                "required": [
                                  "start_position",
                                  "end_position",
                                  "range_type"
                                ],
                                "properties": {
                                  "start_position": {
                                    "type": "integer"
                                  },
                                  "end_position": {
                                    "type": "integer"
                                  },
                                  "range_type": {
                                    "enum": [
                                      "exclusive",
                                      "inclusive"
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "actions": {
                            "type": "array",
                            "items": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "required": [
                                    "delete"
                                  ],
                                  "properties": {
                                    "delete": {
                                      "type": "object",
                                      "required": [
                                        "start_position",
                                        "end_position",
                                        "range_type"
                                      ],
                                      "properties": {
                                        "start_position": {
                                          "type": "integer"
                                        },
                                        "end_position": {
                                          "type": "integer"
                                        },
                                        "range_type": {
                                          "enum": [
                                            "exclusive",
                                            "inclusive"
                                          ]
                                        }
                                      }
                                    }
                                  }
                                },
                                {
                                  "type": "object",
                                  "required": [
                                    "insert"
                                  ],
                                  "properties": {
                                    "insert": {
                                      "type": "object",
                                      "required": [
                                        "position",
                                        "value"
                                      ],
                                      "properties": {
                                        "position": {
                                          "type": "integer"
                                        },
                                        "value": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  }
                                },
                                {
                                  "type": "object",
                                  "required": [
                                    "move_cursor"
                                  ],
                                  "properties": {
                                    "move_cursor": {
                                      "type": "object",
                                      "required": [
                                        "position"
                                      ],
                                      "properties": {
                                        "position": {
                                          "type": "integer"
                                        }
                                      }
                                    }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
  /functions:
    description: Retrieve the BEL function resource collection.
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /functions/{fx}:
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /namespaces:
  /namespaces/{namespace}:

  /namespaces/{namespace}/equivalents:
    post:
  /namespaces/{namespace}/orthologs:
    post:
  /namespaces/{namespace}/{value}:
  /namespaces/{namespace}/{value}/equivalents/namespaces/{target}:
  /namespaces/{namespace}/{value}/orthologs/namespaces/{target}:
# vim: ft=yaml sw=2 ts=2 sts=2 expandtab:

#%RAML 0.8
title: OpenBEL API
version: 0.0.2
baseUri: http://next.belframework.org
schemas:
  - evidence: !include http://next.belframework.org/schema/evidence.schema.json
/api:
  description: The root resource collection.
  get:
    headers:
        Accept:
          displayName: Accept
    responses:
      200:
        body:
          application/hal+json:
            example: |
              {
                "_links": {
                  "item": [
                    {
                      "href": "http://next.belframework.org/api/annotations"
                    },
                    {
                      "href": "http://next.belframework.org/api/evidence"
                    },
                    {
                      "href": "http://next.belframework.org/api/expressions"
                    },
                    {
                      "href": "http://next.belframework.org/api/functions"
                    },
                    {
                      "href": "http://next.belframework.org/api/namespaces"
                    }
                  ]
                }
              }
  /annotations:
    description: Represents the annotation resource collection.
    get:
      description: Retrieves all annotation resources.
    /{annotation}:
      description: Represents a single annotation resource.
      get:
        description: Retrieves an annotation resource.
      /{annotation}/values:
        description: Represents all annotation value resources available on the annotation resource identified by *{annotation}*.
        /{value}:
          description: Represents a single annotation value resources available on the annotation resource identified by *{annotation}* and *{value}*.
          get:
            description:
  /evidence:
    description: |
      Operate on the evidence resource collection.

      *Operations*

      - Filter the evidence resource collection using `GET /evidence` with query parameters.
      - Retrieve an evidence resource using `GET /evidence/{id}`.
      - Create a new evidence resource using `POST /evidence` with a supported content type.
      - Update an existing evidence resource using `PUT /evidence/{id}` with a supported content type.
      - Delete an existing evidence resource using `DELETE /evidence/{id}`.

    post:
      description: |
        Create an evidence resource.

        Include a *profile* parameter in the *Content-Type* header to convey the schema evidence schema for the JSON document.

        *Example*:

        - `Content-Type: application/json; profile=http://next.belframework.org/schema/evidence.schema.json`
      responses:
        201:
          description: |
            *201 Created*

            The evidence resource was created.

            The link to the evidence resource is conveyed is the *Link* header.
        415:
          description: |
            *415 Unsupported Media Type*

            The evidence resource body was not a supported media type..
      body:
        application/json:
          schema: evidence
    get:
      description: |
        Retrieve the evidence resource collection.

        This collection must be paged using *offset* (defaults to `0`) as the start index and *length* (defaults to `100`) as the number of evidence resources to return.

        This collection can be filtered by specifying one or more *filter* query parameters. A filter query parameter specifies the *category*, *name*, and *value* of the filter and is encoded as a JSON object. For example the citation id filter might be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101"
          }
        ```

        This collection includes a *facets* array where each facet value is captured individually. For example for the citation id filter the facet object would be encoded as:

        ```json
          {
            "category": "citation",
            "name": "id",
            "value": "133785101",
            "filter": "{\"category\": \"citation\", \"name\": \"id\", \"value\": \"133785101\"}",
            "count": 25
          }
        ```

        The *filter* property value has the same form as the *filter* query parameter. This is intended to support filtering the evidence resource collection by selected facets.
      headers:
        Accept:
          displayName: Accept
          description: |
            The Accept header informs the server which media types the client accepts.
      queryParameters:
        offset:
          type: integer
          description: The evidence resource index that starts a page of the evidence resource collection.
          example: 0
          required: false
        length:
          type: integer
          description: The length of the evidence resource collection to retrieve.
          example: 100
          required: false
        filter:
          type: string
          description: A filter to apply to the evidence resource collection to narrow the resources retrieved.
          example: |
            {"category":"context","name":"Anatomy","value":"prostate gland"}
          required: false
      responses:
        200:
          description: |
            An example path for this resource might be `http://next.belframework.org/api/evidence?offset=0&length=1&filter={%22category%22:%22context%22,%22name%22:%22Anatomy%22,%22value%22:%22prostate%20gland%22}`.
          body:
            application/json:
              example: |
                {
                  "_embedded": {
                    "evidence": [
                      {
                        "bel_statement": "p(HGNC:CDH1) decreases cat(complex(p(HGNC:ITGAV),p(HGNC:ITGB5)))",
                        "citation": {
                          "type": "Other",
                          "name": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer",
                          "id": "Landes Bioscience - Altered Integrin Expression in Three Common Types of Human Cancer=Breast Cancer"
                        },
                        "biological_context": {
                          "Species": "9606"
                        },
                        "metadata": {
                          "status": "Review"
                        }
                      }
                    ]
                  },
                  "facets": [
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "9606",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"9606\"}",
                      "count": 49071
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10090",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10090\"}",
                      "count": 19416
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Review",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Review\"}",
                      "count": 18954
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Approved",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Approved\"}",
                      "count": 18947
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Rejected",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Rejected\"}",
                      "count": 18896
                    },
                    {
                      "category": "metadata",
                      "name": "status",
                      "value": "Draft",
                      "filter": "{\"category\":\"metadata\",\"name\":\"status\",\"value\":\"Draft\"}",
                      "count": 18784
                    },
                    {
                      "category": "context",
                      "name": "Species",
                      "value": "10116",
                      "filter": "{\"category\":\"context\",\"name\":\"Species\",\"value\":\"10116\"}",
                      "count": 7091
                    },
                    {
                      "category": "context",
                      "name": "Anatomy",
                      "value": "liver",
                      "filter": "{\"category\":\"context\",\"name\":\"Anatomy\",\"value\":\"liver\"}",
                      "count": 2357
                    }
                  ]
                }
    /{identifier}:
      description:
      get:
      put:
        description: |
          Replaces an evidence resource identified by *{identifier}*.

          Include a *profile* parameter in the *Content-Type* header to convey the schema evidence schema for the JSON document.

          *Example*:

          - `Content-Type: application/json; profile=http://next.belframework.org/schema/evidence.schema.json`
        body:
          application/json:
            schema: evidence
        responses:
          202:
            description: |
              *202 Accepted*

              The replacement for the evidence resource will be applied.
          404:
            description: |
              *404 Not Found*

              An evidence resource, identified by *{identifier}*, does not exist.
          415:
            description: |
              *415 Unsupported Media Type*

              The evidence resource body was not a supported media type.
      patch:
      delete:
  /expressions/{bel}/completions:
    description: |
      Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

      Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

      Custom Caret Position:

      The caret position can be provided to indicate where to complete from.

      Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
    uriParameters:
      bel:
        type: string
        description: BEL statement fragment; Completions will be provided for this input.
        required: false
    get:
      description: |
        Retrieve completions for the *BEL* expression fragment. The caret position to complete from defaults to the end of *BEL* expression fragment.

        Examples:

        - *aabund* yields functions *microRNAAbundance* and *rnaAbundance*
        - *p(H* yields functions *chaperoneActivity*, *pathology*, *phosphataseActivity* and namespace prefixes *CHEBI*, *CHEBIID*, *HGNC*, *MESHCS*, *MESHD*, *MESHPP*, *SCHEM*
        - *tscript(p(HGNC:* yields namespace values *AKT1*, *AKT2*, etc.

        Custom Caret Position:

        The caret position can be provided to indicate where to complete from.

        Examples:

        - *pro(HGNC:*, *caret_position*: `2` yields functions *biologicalProcess*, *products*, *proteinAbundance*, and *proteinModification*
      headers:
        Accept:
          displayName: Accept
      queryParameters:
        caret_position:
          type: integer
          description: The position of the caret within the *bel* input. Defaults to the right-most caret_position for *bel* (e.g. length of *bel* input).
          example: 0
          required: false
      responses:
        200:
          body:
            application/json:
              example: |
                [
                  {
                    "completion": {
                      "type": "namespace_prefix",
                      "label": "HGNC",
                      "value": "HGNC:",
                      "highlight": {
                        "start_position": 2,
                        "end_position": 3,
                        "range_type": "inclusive"
                      },
                      "actions": [
                        {
                          "delete": {
                              "start_position": 2,
                              "end_position": 3,
                              "range_type": "inclusive"
                          },
                          "insert": {
                              "position": 2,
                              "value": "HGNC:"
                          },
                          "move_cursor": {
                              "position": 7
                          }
                        }
                      ]
                    }
                  }
                ]
              schema: |
                {
                  "$schema": "http://json-schema.org/draft-04/schema",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "completion"
                    ],
                    "properties": {
                      "completion": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "type",
                          "label",
                          "value",
                          "highlight",
                          "actions"
                        ],
                        "properties": {
                          "type": {
                            "enum": [
                              "function",
                              "namespace_prefix",
                              "namespace_value"
                            ]
                          },
                          "label": {
                            "type": "string"
                          },
                          "value": {
                            "type": "string"
                          },
                          "highlight": {
                            "oneOf": [
                              {
                                "type": "null"
                              },
                              {
                                "type": "object",
                                "required": [
                                  "start_position",
                                  "end_position",
                                  "range_type"
                                ],
                                "properties": {
                                  "start_position": {
                                    "type": "integer"
                                  },
                                  "end_position": {
                                    "type": "integer"
                                  },
                                  "range_type": {
                                    "enum": [
                                      "exclusive",
                                      "inclusive"
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "actions": {
                            "type": "array",
                            "items": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "required": [
                                    "delete"
                                  ],
                                  "properties": {
                                    "delete": {
                                      "type": "object",
                                      "required": [
                                        "start_position",
                                        "end_position",
                                        "range_type"
                                      ],
                                      "properties": {
                                        "start_position": {
                                          "type": "integer"
                                        },
                                        "end_position": {
                                          "type": "integer"
                                        },
                                        "range_type": {
                                          "enum": [
                                            "exclusive",
                                            "inclusive"
                                          ]
                                        }
                                      }
                                    }
                                  }
                                },
                                {
                                  "type": "object",
                                  "required": [
                                    "insert"
                                  ],
                                  "properties": {
                                    "insert": {
                                      "type": "object",
                                      "required": [
                                        "position",
                                        "value"
                                      ],
                                      "properties": {
                                        "position": {
                                          "type": "integer"
                                        },
                                        "value": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  }
                                },
                                {
                                  "type": "object",
                                  "required": [
                                    "move_cursor"
                                  ],
                                  "properties": {
                                    "move_cursor": {
                                      "type": "object",
                                      "required": [
                                        "position"
                                      ],
                                      "properties": {
                                        "position": {
                                          "type": "integer"
                                        }
                                      }
                                    }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
  /functions:
    description: Retrieve the BEL function resource collection.
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /functions/{fx}:
    get:
      headers:
        Accept:
          displayName: Accept
      responses:
        200:
  /namespaces:
  /namespaces/{namespace}:

  /namespaces/{namespace}/equivalents:
    post:
  /namespaces/{namespace}/orthologs:
    post:
  /namespaces/{namespace}/{value}:
  /namespaces/{namespace}/{value}/equivalents/namespaces/{target}:
  /namespaces/{namespace}/{value}/orthologs/namespaces/{target}:
# vim: ft=yaml sw=2 ts=2 sts=2 expandtab:


update api doc

update api doc

#%RAML 1.0
title: GTS API
version:0.3.1
protocols: [HTTP, HTTPS]
baseUri: http://server-url/deployed-app/operations
mediatype: application/json
types: !include ggs-types.raml
/api:
	options:
		description: Retrieve specific description for resources (API)
		responses:
			200:
				body:
					application/json:
						type: ResourceDef[]
/jts:
	/buffer:
		post:
			description: calculates the geometry buffer sent in the body. Beware of the buffer in geometries with projection wgs84
			mediaType: application/json
			queryParameters:
				distance:
					displayName: distance
					type: double
					description: buffer to apply
					example: 0.5
					required: true
				segments:
					displayName: segments
					type: integer
					description: quadrants segments to build arcs.
					example: 3
					required: false
					defaultValue: 8 (see JTS documentation)
			body:
				application/json:
					type: FlatGeometry
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
	/union:
		post:
			description: calculates the geometry resulting from the union of the geometries sent in the body
			mediaType: application/json
			body:
				type: FlatGeometry[]
					miItems: 2
					uniqueItems: true
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
		/combined:
			post:
				description: Combine a collection of FlatGeometry into a new FlatGeometry, keeping vector boundaries
				mediaType: application/json
				body:
					type: FlatGeometry[]
						miItems: 2
						uniqueItems: true
				responses:
					201:
						body:
							application/json:
								type: FlatGeometry
		/overlaped:
			post:
				description: Calculate the geometric union (keeping vector boundaries) of source and overlay data sent in the body
				mediaType: application/json
				body:
					type: OperationData
				responses:
					201:
						body:
							application/json:
								type: FlatGeometry[]

	/envelope:
		post:
			description: calculates the envelope of the geometry sent in the body
			mediaType: application/json
			body:
				type: FlatGeometry
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
	/centroid:
		post:
			description: calculates the centroid of the geometry sent in the body
			mediaType: application/json
			body:
				type: FlatGeometry
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
	/intersection:
		post:
			description: calculates the outline geometry resulting from the intersection of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
		/elements:
			post:
				description: calculates an array of geometries resulting from the intersection of source and overlay data sent in the body
				mediaType: application/json
				queryParameters:
					tolerance:
						displayName: tolerance
						type: double
						description: tolerance to apply operation
						example: -0.00001
						required: false
						defaultValue: -0.00001
				body:
					type: OperationData
				responses:
					201:
						body:
							application/json:
								type: FlatGeometry[]
	/difference:
		post:
			description: calculates the outline geometry resulting from the difference of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
		/elements:
			post:
				description: calculates an array of geometries resulting from the difference of source and overlay data sent in the body
				mediaType: application/json
				queryParameters:
					tolerance:
						displayName: tolerance
						type: double
						description: tolerance to apply operation
						example: -0.00001
						required: false
						defaultValue: -0.00001
				body:
					type: OperationData
				responses:
					201:
						body:
							application/json:
								type: FlatGeometry[]
	/sym-difference:
		post:
			description: calculates the outline geometry resulting from the symmetric difference of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
		/elements:
			post:
				description: calculates an array of geometries resulting from the symmetric difference of source and overlay data sent in the body
				mediaType: application/json
				queryParameters:
					tolerance:
						displayName: tolerance
						type: double
						description: tolerance to apply operation
						example: -0.00001
						required: false
						defaultValue: -0.00001
				body:
					type: OperationData
				responses:
					201:
						body:
							application/json:
								type: FlatGeometry[]
	/intersect/elements:
		post:
			description: Calculates the geometries in source that intersects with overlay data, sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: 0.001
					required: false
					defaultValue: 0.001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry[]

#%RAML 1.0
title: GTS API
version:0.1.0
protocols: [HTTP, HTTPS]
baseUri: http://server-url/deployed-app/operations
mediatype: application/json
types: !include ggs-types.raml
/api:
	options:
		description: Retrieve specific description for resources (API)
		responses:
			200:
				body:
					application/json:
						type: ResourceDef[]
/jts:
	/buffer:
		post:
			description: calculates the geometry buffer sent in the body. Beware of the buffer in geometries with projection wgs84
			mediaType: application/json
			queryParameters:
				distance:
					displayName: distance
					type: double
					description: buffer to apply
					example: 0.5
					required: true
				segments:
					displayName: segments
					type: integer
					description: quadrants segments to build arcs.
					example: 3
					required: false
					defaultValue: 8 (see JTS documentation)
			body:
				application/json:
					type: FlatGeometry
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
	/union:
		post:
			description: calculates the geometry resulting from the union of the geometries sent in the body
			mediaType: application/json
			body:
				type: FlatGeometry[]
					miItems: 2
					uniqueItems: true
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry

/envelope:
		post:
			description: calculates the envelope of the geometry sent in the body
			mediaType: application/json
			body:
				type: FlatGeometry
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
/centroid:
		post:
			description: calculates the centroid of the geometry sent in the body
			mediaType: application/json
			body:
				type: FlatGeometry
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
/intersection:
		post:
			description: calculates the outline geometry resulting from the intersection of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
/intersection/elements:
		post:
			description: calculates an array of geometries resulting from the intersection of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry[]
/difference:
		post:
			description: calculates the outline geometry resulting from the difference of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
/difference/elements:
		post:
			description: calculates an array of geometries resulting from the difference of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry[]
/sym-difference:
		post:
			description: calculates the outline geometry resulting from the symmetric difference of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry
/sym-difference/elements:
		post:
			description: calculates an array of geometries resulting from the symmetric difference of source and overlay data sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: -0.00001
					required: false
					defaultValue: -0.00001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry[]
/intersect/elements:
		post:
			description: Calculates the geometries in source that intersects with overlay data, sent in the body
			mediaType: application/json
			queryParameters:
				tolerance:
					displayName: tolerance
					type: double
					description: tolerance to apply operation
					example: 0.001
					required: false
					defaultValue: 0.001
			body:
				type: OperationData
			responses:
				201:
					body:
						application/json:
							type: FlatGeometry[]