openapi: 3.2.0
info:
  title: Folio Loadable Roles API
  version: v1
  description: 'Operations tagged loadable-roles across 2 of this provider''s published API definitions: folio-mod-roles-keycloak-openapi.json, folio-mod-roles-keycloak-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:8081
  description: Locally deployed server
tags:
- name: loadable-roles
paths:
  /loadable-roles:
    get:
      description: Get loadable roles by query
      operationId: findLoadableRoles
      tags:
      - loadable-roles
      parameters:
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '201':
          description: Array of roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/loadableRoles'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Find loadable roles
      x-summary-source: derived
    put:
      description: A default role is created or updated, role is populated with the specified permissions (capabilities and capability sets) as they become available in the system. Default role cannot be changed via Roles API.
      operationId: upsertLoadableRole
      tags:
      - loadable-roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/loadableRole'
      responses:
        '200':
          description: Default loadable role was created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/loadableRole'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Upsert loadable role
      x-summary-source: derived
    servers:
    - url: http://localhost:8081
      description: Locally deployed server
components:
  parameters:
    offset:
      in: query
      name: offset
      description: Skip over a number of elements by specifying an offset value for the query.
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
      example: 2
    query:
      in: query
      name: query
      description: A query string to filter users based on matching criteria in fields.
      required: false
      schema:
        type: string
      example: role
    limit:
      in: query
      name: limit
      description: Limit the number of elements returned in the response.
      required: false
      schema:
        type: integer
        default: 10
        minimum: 0
      example: 20
  schemas:
    loadableRoles:
      $schema: http://json-schema.org/draft-04/schema#
      id: loadableRoles.json
      title: List of Loadable Roles Schema
      description: List of loadable roles
      type: object
      properties:
        loadableRoles:
          description: List of loadable roles
          type: array
          items:
            $ref: '#/components/schemas/loadableRole'
          minItems: 1
        totalRecords:
          readOnly: true
          description: The total number of records matching the provided criteria
          type: integer
          format: int64
      required:
      - loadableRoles
    errors:
      description: A set of errors
      $schema: http://json-schema.org/draft-04/schema#
      type: object
    loadablePermission:
      $schema: http://json-schema.org/draft-04/schema#
      id: loadablePermission.json
      title: Loadable Permission schema
      description: Loadable Permission
      type: object
      properties:
        roleId:
          description: Loadable Role identifier
          type: string
          format: uuid
        permissionName:
          description: Permission name
          type: string
        capabilityId:
          description: Capability Id associated with this permission
          type: string
          format: uuid
        capabilitySetId:
          description: Capability Set Id associated with this permission
          type: string
          format: uuid
        metadata:
          readOnly: true
          $ref: '#/components/schemas/metadata'
      required:
      - permissionName
    loadableRole:
      $schema: http://json-schema.org/draft-04/schema#
      title: Loadable Role schema
      description: Loadable Role
      type: object
      allOf:
      - $ref: '#/components/schemas/role'
      properties:
        permissions:
          description: List of permissions associated with role
          type: array
          items:
            $ref: '#/components/schemas/loadablePermission'
    role:
      $schema: http://json-schema.org/draft-04/schema#
      title: Role schema
      description: Role
      type: object
      properties:
        id:
          description: Role identifier
          type: string
          format: uuid
        name:
          description: A human-readable name/label for this role. Must not contain a '/' character
          type: string
          minLength: 1
          maxLength: 255
          pattern: ^[^/]+$
        description:
          description: Free form description of the role
          type: string
        type:
          description: Role type
          $ref: '#/components/schemas/roleType'
        metadata:
          readOnly: true
          $ref: '#/components/schemas/metadata'
      required:
      - name
    roleType:
      $schema: http://json-schema.org/draft-04/schema#
      type: string
      description: Role type
      enum:
      - DEFAULT
      - REGULAR
      - CONSORTIUM
    metadata:
      $schema: http://json-schema.org/draft-04/schema#
      title: Metadata Schema
      description: Metadata about creation and changes to records, provided by the server (client should not provide)
      type: object
      properties:
        createdDate:
          description: Date and time when the record was created
          type: string
          format: date-time
        createdByUserId:
          description: ID of the user who created the record (when available)
          type: string
          format: uuid
        updatedDate:
          description: Date and time when the record was last updated
          type: string
          format: date-time
        updatedByUserId:
          description: ID of the user who last updated the record (when available)
          type: string
          format: uuid
      additionalProperties: false
  responses:
    internalServerErrorResponse:
      description: Error response for unhandled or critical server exceptions, e.g. NullPointerException.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            $ref: '#/components/examples/internalServerErrorResponse'
    badRequestResponse:
      description: Error response in JSON format for validation errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          example:
            $ref: '#/components/examples/badRequestResponse'
  examples:
    internalServerErrorResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    badRequestResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
x-refined-from:
- folio-mod-roles-keycloak-openapi.json
- folio-mod-roles-keycloak-openapi.yml