settings.yaml

openapi: 3.0.0
info:
  title: Settings
  version: v1
paths:
  /settings/entries:
    parameters:
      - $ref: headers/okapi-permissions.yaml
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: headers/okapi-user.yaml
      - $ref: parameters/limit.yaml
      - $ref: parameters/offset.yaml
      - $ref: parameters/query.yaml
    get:
      description: >
        Get settings with optional CQL query.
        If X-Okapi-Permissions includes settings.global.read then settings
        without a userId are returned.
        If X-Okapi-Permissions includes settings.users.read then settings
        with a userId are returned.
        If X-Okapi-Permissions includes settings.owner.read then settings
        with userId = current-user are returned.
      operationId: getSettings
      responses:
        "200":
          description: Setting entries
          content:
            application/json:
              schema:
                $ref: schemas/entries.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
    post:
      description: >
        Create setting entry.
        If X-Okapi-Permissions includes settings.global.write, then a setting without
        a userId may be created.
        If X-Okapi-Permissions includes settings.users.write, then a setting with a
        userId may be created.
        If X-Okapi-Permissions includes settings.owner.write, then a setting with
        userId = current-user may be created.
      operationId: postSetting
      requestBody:
        content:
          application/json:
            schema:
              $ref: schemas/entry.json
      responses:
        "204":
          description: Setting created
        "400":
          $ref: "#/components/responses/trait_400"
        "403":
          $ref: "#/components/responses/trait_403"
        "413":
          $ref: "#/components/responses/trait_413"
        "500":
          $ref: "#/components/responses/trait_500"
  /settings/entries/{id}:
    parameters:
      - $ref: headers/okapi-permissions.yaml
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: headers/okapi-user.yaml
      - in: path
        name: id
        required: true
        description: Settings entry identifier
        schema:
          type: string
          format: uuid
    get:
      description: >
        Get setting.
        If X-Okapi-Permissions includes settings.global.read, then a setting without
        a userId may be retrieved.
        If X-Okapi-Permissions includes settings.users.read, then a setting with a
        userId may be retrieved.
        If X-Okapi-Permissions includes settings.owner.read, then a setting with
        userId = current-user may be retrieved.
      operationId: getSetting
      responses:
        "200":
          description: Configuration entry
          content:
            application/json:
              schema:
                $ref: schemas/entry.json
        "400":
          $ref: "#/components/responses/trait_400"
        "403":
          $ref: "#/components/responses/trait_403"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
    put:
      description: >
        Update setting.
        If X-Okapi-Permissions includes settings.global.write, then a setting without
        a userId may be updated.
        If X-Okapi-Permissions includes settings.users.write, then a setting with a
        userId may be updated.
        If X-Okapi-Permissions includes settings.owner.write, then a setting with
        userId = current-user may be updated.
      operationId: putSetting
      requestBody:
        content:
          application/json:
            schema:
              $ref: schemas/entry.json
      responses:
        "204":
          description: Setting updated
        "400":
          $ref: "#/components/responses/trait_400"
        "403":
          $ref: "#/components/responses/trait_403"
        "404":
          $ref: "#/components/responses/trait_404"
        "413":
          $ref: "#/components/responses/trait_413"
        "500":
          $ref: "#/components/responses/trait_500"
    delete:
      description: >
        Delete setting.
        If X-Okapi-Permissions includes settings.global.write, then a setting without
        a userId may be deleted.
        If X-Okapi-Permissions includes settings.users.write, then a setting with a
        userId may be deleted.
        If X-Okapi-Permissions includes settings.owner.write, then a setting with
        userId = current-user may be deleted.
      operationId: deleteSetting
      responses:
        "204":
          description: Setting deleted
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /settings/upload:
    parameters:
      - $ref: headers/okapi-permissions.yaml
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: headers/okapi-user.yaml
    put:
      description: >
        Upload settings. The entries are inserted or updated depending on whether
        key, scope, userId already. Each entry gets a unique identifier assigned
        if it's a new setting. The id must not be supplied.
        If X-Okapi-Permissions includes settings.global.write, then a setting without
        a userId may be created/updated.
        If X-Okapi-Permissions includes settings.users.write, then a setting with a
        userId may be created/updated.
        If X-Okapi-Permissions includes settings.owner.write, then a setting with
        userId = current-user may be created/updated.
      operationId: uploadSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: schemas/uploadRequest.json
      responses:
        "200":
          description: Settings uploaded
          content:
            application/json:
              schema:
                $ref: schemas/uploadResponse.json
        "400":
          $ref: "#/components/responses/trait_400"
        "403":
          $ref: "#/components/responses/trait_403"
        "500":
          $ref: "#/components/responses/trait_500"

components:
  responses:
    trait_400:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
            example: Invalid JSON in request
        application/json:
          schema:
            type: object
            example: {"error":"Invalid JSON in request"}
    trait_403:
      description: Forbidden
      content:
        text/plain:
          schema:
            type: string
            example: Insufficient permissions to access resource
        application/json:
          schema:
            type: object
            example: {"error":"Insufficient permissions to access resource"}
    trait_404:
      description: Not Found
      content:
        text/plain:
          schema:
            type: string
            example: Identifier 596d9f60-cda3-44d2-a4a1-2f48b7d4d23c not found
        application/json:
          schema:
            type: object
            example: {"error":"Identifier 596d9f60-cda3-44d2-a4a1-2f48b7d4d23c not found"}
    trait_413:
      description: Payload Too Large
      content:
        text/plain:
          schema:
            type: string
    trait_500:
      description: Internal error
      content:
        text/plain:
          schema:
            type: string
            example: Internal server error, contact administrator
  schemas:
    errors:
      $ref: schemas/errors.json