openapi: 3.0.0
info:
  title: Grants Config Broker API
  description: API for managing and retrieving grant configurations and versions.
  version: 1.0.0
servers:
  - url: 'http://localhost:3001'
    description: Local server URL
  - url: https://ephemeral-protected.api.dev.cdp-int.defra.cloud/grants-config-broker
    description: Dev environment
  - url: https://ephemeral-protected.api.test.cdp-int.defra.cloud/grants-config-broker
    description: Test environment
  - url: https://ephemeral-protected.api.ext-test.cdp-int.defra.cloud/grants-config-broker
    description: Ext-test environment
  - url: https://ephemeral-protected.api.perf-test.cdp-int.defra.cloud/grants-config-broker
    description: Perf-test environment
paths:
  /api/latestVersion:
    get:
      summary: Get latest version of config for a given grant
      description: Returns the latest configuration version for a specified grant, with options to include draft versions and apply version constraints.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: grant
          in: query
          required: true
          schema:
            type: string
          description: The name of the grant.
        - name: draft
          in: query
          required: false
          schema:
            type: string
            enum: [include, only]
          description: Filter for draft versions.
        - name: constrainMajor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Constraint for the major version. Required if constrainMinor is provided.
        - name: constrainMinor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Constraint for the minor version.
      responses:
        '200':
          description: Successfully retrieved the latest version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Grant or version not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/version:
    get:
      summary: Get specific version of config for a given grant
      description: Returns a specific version of the configuration for a given grant, identified by either a full version string or major, minor, and patch components.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: grant
          in: query
          required: true
          schema:
            type: string
          description: The name of the grant.
        - name: version
          in: query
          required: false
          schema:
            type: string
          description: Full version string (e.g., "1.2.3"). If not provided, major, minor, and patch are required.
        - name: major
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Major version component.
        - name: minor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Minor version component.
        - name: patch
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Patch version component.
      responses:
        '200':
          description: Successfully retrieved the specific version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Grant or version not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/allVersions:
    get:
      summary: Get info on all versions of config for a given grant
      description: Returns a list of all configuration versions for a specified grant, with filtering options.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: grant
          in: query
          required: true
          schema:
            type: string
          description: The name of the grant.
        - name: draft
          in: query
          required: false
          schema:
            type: string
            enum: [include, only]
          description: Filter for draft versions.
        - name: constrainMajor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Constraint for the major version.
        - name: constrainMinor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Constraint for the minor version.
      responses:
        '200':
          description: Successfully retrieved all versions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VersionResponse'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/allGrants:
    get:
      summary: Get info on all versions of all grants
      description: Returns a list of all versions for all grants.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: draft
          in: query
          required: false
          schema:
            type: string
            enum: [include, only]
          description: Filter for draft versions.
      responses:
        '200':
          description: Successfully retrieved all grants versions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VersionResponse'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/versionHistory:
    get:
      summary: Get version history for a version of a grant
      description: Returns the history of changes for a specific version of a grant.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: grant
          in: query
          required: true
          schema:
            type: string
          description: The name of the grant.
        - name: version
          in: query
          required: false
          schema:
            type: string
          description: Full version string.
        - name: major
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Major version component.
        - name: minor
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Minor version component.
        - name: patch
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Patch version component.
      responses:
        '200':
          description: Successfully retrieved version history.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Details of the version history entry.
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Grant or version not found.

  /api/release-config:
    post:
      summary: Post release config for a given grant
      description: Submits a release configuration for a specific grant and version, including a list of files.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostReleaseConfigRequest'
      responses:
        '202':
          description: Accepted - Release configuration received and processed.
        '204':
          description: No Content - Release configuration received but no action taken (e.g., version already exists).
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized - Invalid or missing authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/feature-control/{name}:
    get:
      summary: Get a single feature control by name
      description: Returns the basic details of a feature control, excluding its history.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The unique name of the feature control.
      responses:
        '200':
          description: Successfully retrieved the feature control.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureControl'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized.
        '404':
          description: Not Found - Feature control does not exist.
  /api/feature-control/{name}/detailed:
    get:
      summary: Get a single feature control by name with full details
      description: Returns the full details of a feature control, including its update history.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The unique name of the feature control.
      responses:
        '200':
          description: Successfully retrieved the detailed feature control.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedFeatureControl'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized.
        '404':
          description: Not Found - Feature control does not exist.
    post:
      summary: Add or update a feature control definition
      description: Creates a new feature control or updates the definition of an existing one. Immutable fields (name, type, initialValue) cannot be updated.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFeatureControlRequest'
      responses:
        '202':
          description: Accepted - Feature control created or updated.
        '204':
          description: No Content - No changes made to the existing feature control.
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized.
        '409':
          description: Conflict - Attempted to update an immutable field.
    put:
      summary: Update a feature control value
      description: Updates the current value of a feature control for the current environment.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutFeatureControlValueRequest'
      responses:
        '202':
          description: Accepted - Feature control value updated.
        '400':
          description: Bad Request - Validation error (e.g., value doesn't match type).
        '401':
          description: Unauthorized.
        '404':
          description: Not Found - Feature control does not exist.

  /api/feature-controls:
    get:
      summary: Get a list of feature controls
      description: Returns a paginated list of feature controls with optional filtering by name, scope, or type.
      security:
        - bearerAuth: []
          apiKey: []
      parameters:
        - $ref: '#/components/parameters/cdpRequestId'
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: name
          in: query
          required: false
          schema:
            type: string
          description: Partial name match (case-insensitive).
        - name: owner
          in: query
          required: false
          schema:
            type: string
          description: Partial owner match (case-insensitive).
        - name: scope
          in: query
          required: false
          schema:
            type: string
          description: Exact scope match.
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [list-string, list-number, boolean, date, string, number]
          description: Exact type match.
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [active, expired, withdrawn]
          description: Exact status match.
      responses:
        '200':
          description: Successfully retrieved the list of feature controls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureControlsResponse'
        '400':
          description: Bad Request - Validation error.
        '401':
          description: Unauthorized.

components:
  schemas:
    FeatureControl:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum: [list-string, list-number, boolean, date, string, number]
        value:
          $ref: '#/components/schemas/FeatureControlValue'
        scopes:
          type: array
          items:
            type: string
    DetailedFeatureControl:
      allOf:
        - $ref: '#/components/schemas/FeatureControl'
        - type: object
          properties:
            status:
              type: string
              enum: [active, expired, withdrawn]
            displayName:
              type: string
            description:
              type: string
            owner:
              type: string
            createdBy:
              type: string
            expiryDate:
              type: string
              format: date-time
            roleRequired:
              type: array
              items:
                type: string
            created:
              type: string
              format: date-time
            lastUpdated:
              type: string
              format: date-time
            lastUpdatedBy:
              type: string
            history:
              type: array
              items:
                $ref: '#/components/schemas/FeatureControlHistory'

    FeatureControlValue:
      oneOf:
        - type: string
        - type: number
        - type: boolean
        - type: array
          items:
            type: string
        - type: array
          items:
            type: number

    FeatureControlHistory:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/FeatureControlValue'
        setBy:
          type: string
        dateTime:
          type: string
          format: date-time
        note:
          type: string

    FeatureControlsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DetailedFeatureControl'
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer

    PostFeatureControlRequest:
      type: object
      required:
        - name
        - type
        - initialValue
        - scopes
        - displayName
        - description
        - owner
        - expiryDate
        - createdBy
      properties:
        name:
          type: string
        type:
          type: string
          enum: [list-string, list-number, boolean, date, string, number]
        initialValue:
          type: object
          description: Mapping of environment to initial value. Must contain 'default' or all of 'dev', 'test', 'ext-test', 'perf-test', 'prod'.
          additionalProperties:
            $ref: '#/components/schemas/FeatureControlValue'
        scopes:
          type: array
          items:
            type: string
          minItems: 1
        displayName:
          type: string
        description:
          type: string
        owner:
          type: string
        expiryDate:
          type: string
          format: date-time
        createdBy:
          type: string
        roleRequired:
          type: array
          items:
            type: string

    PutFeatureControlValueRequest:
      type: object
      required:
        - name
        - value
        - user
      properties:
        name:
          type: string
        value:
          $ref: '#/components/schemas/FeatureControlValue'
        user:
          type: string
        note:
          type: string

    PostReleaseConfigRequest:
      type: object
      required:
        - grant
        - version
        - files
      properties:
        grant:
          type: string
          description: The name of the grant.
        version:
          type: string
          description: The version string.
        files:
          type: array
          minItems: 1
          items:
            type: string
          description: A list of files included in the release.
        status:
          type: string
          enum: [draft, active]
          description: The status of the release.
        user:
          type: string
          description: The user performing the release.
    VersionResponse:
      type: object
      properties:
        grant:
          type: string
          description: The name of the grant.
        version:
          type: string
          description: The version string.
        status:
          type: string
          description: The status of the version (e.g., active, draft).
        path:
          type: string
          description: The bucket name or path to the configuration.
        manifest:
          type: object
          description: The configuration manifest details.
        lastUpdated:
          type: string
          format: date-time
          description: The timestamp of the last update.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: The error message.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Bearer <iv>:<authTag>:<encryptedData>
      description: |
        The API uses a Bearer token for authentication.
        The token is an encrypted string in the format `iv:authTag:encryptedData`, which is then base64 encoded.
        Example: `Bearer aXY6YXV0aFRhZzplbmNyeXB0ZWREYXRh` (base64 encoded value of `iv:authTag:encryptedData`).
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Dev API key for use on deployed environments
  parameters:
    cdpRequestId:
      name: x-cdp-request-id
      in: header
      required: false
      schema:
        type: string
      description: A unique identifier for the request, used for tracing.
security:
  - bearerAuth: []
    apiKey: []
  - {} # Allows request without security to show headers in Scalar, though auth is usually required.
    # Note: Scalar might need these headers to be explicitly added to each operation or defined globally.
    # Since we want them "modifiable", we'll add them as parameters.