openapi: 3.1.0
info:
  title: SERV Title Alert API
  version: 1.4.0
  description: |
    ```
    SERV Title Alert API

    Exposes functionality relating to alerting.

    - Subscribe to title alert notifications.

    ```
externalDocs:
  description: Exposes functionality relating to alerting
  url: >-
    https://lrsvic-systems.atlassian.net/wiki/spaces/IPF/pages/2526969858/Title+Alert+API+-+Subscribe+Technical+Specifications
servers:
  - url: https://api.servictoria.io/vicland
    description: Production environment
  - url: https://test.api.servictoria.io/vicland
    description: Test environment
paths:
  /vicland/alert/v1/titles/subscriptions:
    post:
      description: Subscribe to title information by volume/folio
      operationId: Subscribe to title information by volume/folio
      parameters:
        - name: Authorization
          in: header
          description: >
            Used to send a valid OAuth 2 access token. Do not use with the
            "access_token" query. string parameter.
          required: true
          schema:
            pattern: ^.*$
            type: string
        - name: x-correlation-id
          in: header
          description: A unique transaction id used to correlate api requests end to end.
          schema:
            pattern: ^.*$
            type: string
        - name: x-source-system
          in: header
          description: >-
            A unique identification string for the source system. This could be
            a system name or hostname where a system is hosted on multiple
            hosts.
          schema:
            pattern: ^.*$
            type: string
        - name: Content-Type
          in: header
          description: This is the format for what the API sends
          schema:
            pattern: ^.+\/.+|^$
            type: string
            default: application/json
        - name: Accept
          in: header
          description: This is the format for what the API receives
          schema:
            pattern: ^.+\/.+|^$
            type: string
            default: application/json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
        required: false
        x-amf-mediaType: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - oauthClientCredentials: []
  /vicland/alert/v1/health:
    get:
      description: Health Check
      operationId: Health
      parameters:
        - name: x-correlation-id
          in: header
          description: A unique transaction id used to correlate api requests end to end.
          schema:
            type: string
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubscriptionRequest:
      required:
        - customerRef
        - endDateTime
        - startDateTime
        - volumeFolio
      type: object
      properties:
        volumeFolio:
          pattern: >-
            ^(?<VolumeNumber>[0-9]{1,5})/(?<FolioNumber>[0-9]{3})(?<Suffix>[A-Z]?)$
          type: string
          description: >-
            The unique identifier of a land title in the format of 
            volume/folio.
        customerRef:
          maxLength: 200
          type: string
          description: >-
            Customer reference. Useful for differentiating between multiple
            customers.
        startDateTime:
          type: string
          description: >-
            Start datetime for subscription in ISO 8601/RFC3339 format. Timezone
            information must be included.
          format: date-time
          x-amf-examples:
            utc: '2015-07-04T21:00:00Z'
            non-utc: '2015-07-04T21:00:00+10:00'
        endDateTime:
          type: string
          description: >-
            End datetime for subscription in ISO 8601/RFC3339 format. Timezone
            information must be included.
          format: date-time
          x-amf-examples:
            utc: '2015-07-28T21:00:00Z'
            non-utc: '2015-07-28T21:00:00+10:00'
      additionalProperties: false
      description: Title Alert Subscription data type
      example:
        volumeFolio: 9500/906
        customerRef: CBA
        startDateTime: '2024-02-01T00:00:00Z'
        endDateTime: '2024-03-11T00:00:00Z'
    SubscriptionResponse:
      required:
        - subscriptionId
      type: object
      properties:
        subscriptionId:
          maxLength: 200
          type: string
          description: ID(UUID) for Subscription.
      additionalProperties: false
      description: Title Alert Subscribe Call Result
      example:
        subscriptionId: d3ca8a76-4c34-478d-a915-4679ee1bbfce
    ErrorResponse:
      required:
        - code
        - correlationId
        - description
        - errorType
        - timestamp
      type: object
      properties:
        code:
          type: integer
          description: The HTTP Status code of the response.
        errorType:
          type: string
          description: Error Type
        description:
          type: string
          description: Error Description
        timestamp:
          type: string
          description: The time at which the API was invoked
          format: date-time
        correlationId:
          type: string
          description: Unique ID for API request
      additionalProperties: false
      description: What a common error object looks like
      x-amf-examples:
        value:
          code: '400'
          errorType: APIKIT:BAD_REQUEST
          description: Bad Request
          timestamp: '2022-01-17T03:31:09.691Z'
          correlationId: 2aa11828-1243-4026-8ee3-7b5c77cef796
    HealthCheckResponse:
      required:
        - apiName
        - applicationName
        - applicationVersion
        - environment
        - status
      type: object
      properties:
        applicationName:
          type: string
          description: Application Name
        applicationVersion:
          type: string
          description: Application Version
        apiName:
          type: string
          description: API Name
        environment:
          type: string
          description: Environment
        status:
          type: string
          description: Status
      additionalProperties: false
      description: The response for an API health check
      example:
        applicationName: SERV Title Alert API
        applicationVersion: 1.0.9
        apiName: serv-title-alert-api
        environment: DEV
        status: running
securitySchemes:
  oauthClientCredentials:
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: https://auth.servictoria.com.au/oauth/token
        scopes:
          access:access:serv-alert-eapi: Permission to create and update title subscription.
