permissions.raml

#%RAML 1.0
title: Permissions
version: v1
baseUri: http://github.com/org/folio/mod-auth/permissions

documentation:
  - title: mod-permissions API
    content: This module is responsible for managing and retrieving permissions in the FOLIO system

types:
  permission: !include permission.json
  permissionNameObject: !include permissionNameObject.json
  permissionListObject: !include permissionListObject.json
  permissionUser: !include permissionUser.json
  permissionUserListObject: !include permissionUserListObject.json
  permissionNameListObject: !include permissionNameListObject.json
  permissionUpload: !include permissionUpload.json
  errors: !include raml-util/schemas/errors.schema

traits:
  validate: !include raml-util/traits/validation.raml
  pageable:
    queryParameters:
      length:
        description: "The maximum number of results to return."
        required: false
        type: integer
        example: 10
        minimum: 1
        default: 10
        maximum: 2147483647
      start:
        description: "The starting index in a list of results (starts at one)."
        required: false
        type: integer
        minimum: 1
        default: 1
        maximum: 2147483647
  sortable:
    queryParameters:
      sortBy:
        description: "A comma-separated list of fieldnames to sort by"
        required: false
        type: string
  queryable:
    queryParameters:
      query:
        description: "A query string to filter users based on matching criteria in fields."
        required: false
        type: string
  byPermission:
    queryParameters:
      hasPermissions:
        description: "A list of permissions that any returned users must possess."
        required: false
        type: string
  byMember:
    queryParameters:
      memberOf:
        description: "A list of permission names that any returned permission must be a sub-permission of."
        required: false
        type: string
  byOwner:
    queryParameters:
      ownedBy:
        description: "A list of user names that any returned permissions must belong to."
        required: false
        type: string
  indexSelectable:
    queryParameters:
      indexField:
        description: "Specify a field other than 'id' to look up the permission user by"
        required: false
        type: string
        example: "userId"

/perms:
  /users:
    get:
      description: Get a list of users
      is: [
        pageable,
        sortable,
        queryable,
        byPermission
      ]
      responses:
        200:
          body:
            application/json:
              type: permissionUserListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        403:
          description: "Access Denied"
          body:
            text/plain:
              example: "Access Denied"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    post:
      description: Add a new user
      is: [validate]
      body:
        application/json:
          type: permissionUser
      responses:
        201:
          body:
            application/json:
              type: permissionUser
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{id}:
      get:
        description: Get a permission user
        is: [ indexSelectable ]
        responses:
          200:
            body:
              application/json:
                type: permissionUser
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          403:
            description: "Access Denied"
            body:
              text/plain:
                example: "Access Denied"
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User does not exist"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      put:
        description: Modify an existing user
        is: [validate]
        body:
          application/json:
            type: permissionUser
        responses:
          200:
            body:
              application/json:
                type: permissionUser
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      delete:
        description: Remove a user
        responses:
          204:
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      /permissions:
        get:
          description: Get permissions that a user has
          queryParameters:
            expanded:
              description: Recursively return all subpermissions
              required: false
              type: string
              example: "true"
            full:
              description: Return full permission objects, as opposed to just permission names
              required: false
              type: string
              example: "true"
          is: [
              indexSelectable
          ]
          responses:
            200:
              description: "An object of returned permissions"
              body:
                application/json:
                  type: permissionNameListObject
            400:
              description: "Bad request"
              body:
                text/plain:
                  example: "Bad request"
            403:
              description: "Access Denied"
              body:
                text/plain:
                  example: "Access Denied"
            404:
              description: "User not found"
              body:
                text/plain:
                  example: "User not found"
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
        post:
          description: Add a permission to a user
          is: [validate, indexSelectable]
          body:
            application/json:
              type: permissionNameObject
          responses:
            200:
              description: "The added permission"
              body:
                application/json:
                  type: permissionNameObject
            400:
              description: "Bad request"
              body:
                text/plain:
                  example: "Bad request"
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
        /{permissionname}:
          delete:
            description: Remove a permission from a user
            is: [ indexSelectable ]
            responses:
              204:
              400:
                description: "Bad request"
                body:
                  text/plain:
              404:
                description: "Permission not found in user"
                body:
                  text/plain:
                    example: "Permission not found in user"
              500:
                description: "Internal server error"
                body:
                  text/plain:
                    example: "Internal server error"
  /permissions:
    get:
      description: Get a list of existing permissions
      queryParameters:
        expandSubs:
          description: Return one level of subpermissions as objects if true. If false or omitted, expanded will be considered.
          required: false
          type: string
          example: "true"
        expanded:
          description: Recursively return all subpermissions as strings if true. Is only considered if expandSubs is false or omitted.
          required: false
          type: string
          example: "true"
        includeDummy:
          description: "Return placeholder 'dummy' permissions"
          required: false
          type: string
          example: "true"
      is: [
        pageable,
        sortable,
        queryable,
        byMember,
        byOwner
      ]
      responses:
        200:
          body:
            application/json:
              type: permissionListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    post:
      description: Add a new permission
      is: [validate]
      body:
        application/json:
          type: permissionUpload
      responses:
        201:
          body:
            application/json:
              type:
                permissionUpload
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{id}:
      get:
        description: Get an existing permission by id
        responses:
          200:
            body:
              application/json:
                type: permission
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "Permission not found"
            body:
              text/plain:
                example: "Permission not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      put:
        description: Modify an existing permission
        is: [validate]
        body:
          application/json:
            type: permissionUpload
        responses:
          200:
            body:
              application/json:
                type: permissionUpload
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "Permission not found"
            body:
              text/plain:
                example: "Permission not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      delete:
        description: Remove a permission
        responses:
          204:
          400:
            description: "Bad request"
            body:
              text/plain:
                example: "Bad request"
          404:
            description: "Permission not found"
            body:
              text/plain:
                example: "Permission not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
  /purge-deprecated:
    post:
      description: purge deprecated permissions
      responses:
        200:
          description: "A list of permission names purged"
          body:
            application/json:
              type: permissionNameListObject
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"