spec.yml

openapi: 3.1.0
info:
  description: >-
    API spec for technical records v3 service
  version: 1.0.0
  title: "Technical Record v3"
  contact:
    email: user@email.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
paths:
  '/v3/technical-records/search/{searchIdentifier}':
    get:
      summary: 'Search for technical records'
      tags:
        - Search Technical Records
      parameters:
        - in: path
          name: searchIdentifier
          schema:
            type: string
            minLength: 3
            maxLength: 21
          required: true
          description: >-
            The identifier to use in the search.
        - in: query
          name: searchCriteria
          schema:
            type: string
            default: all
            enum:
              - all
              - vin
              - primaryVrm
              - partialVin
              - trailerId
              - systemNumber
          description: >-
            The parameter is used to specify which search criteria
            should be used.
      responses:
        '200':
          description: Search result returned
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/techRecordGETComplete'
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
  '/v3/technical-records/{systemNumber}/{createdTimestamp}':
    get:
      summary: 'Get a complete technical record'
      tags:
        - Get a Technical Record
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      responses:
        '200':
          description: Returns the updated technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"

        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
        '500':
          description: Internal Server Error
    patch:
      summary: 'Patch a Technical Record'
      tags:
        - Patch a Technical Record
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      requestBody:
        required: true
        description: The technical record to be updated
        content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordPUTComplete"
                  - $ref: "#/components/schemas/techRecordPUTSkeleton"
                  - $ref: "#/components/schemas/techRecordPUTTestable"
      responses:
        '200':
          description: Returns the complete technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
        '422':
          description: Unprocessable request
        '500':
          description: Validation Error
  '/v3/technical-records':
    post:
      summary: 'Creates a new tech-record'
      tags:
        - Create Technical Record
      requestBody:
        required: true
        description: The technical record to be created
        content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordPUTComplete"
                  - $ref: "#/components/schemas/techRecordPUTSkeleton"
                  - $ref: "#/components/schemas/techRecordPUTTestable"
      responses:
        '200':
          description: Returns the created technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
        '422':
          description: Unprocessable request
        '500':
          description: Validation Error
  '/v3/technical-records/archive/{systemNumber}/{createdTimestamp}':
    patch:
      summary: 'Archive an existing current or provisional technical record'
      tags:
        - Archive Technical Record
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      responses:
        '200':
          description: Returns the updated technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
        '422':
          description: Unprocessable request
        '500':
          description: Validation Error
  '/v3/technical-records/unarchive/{systemNumber}/{createdTimestamp}':
    post:
      summary: 'Unarchive an archived technical record which has no other non-archived technical records which share the same VRM'
      tags:
        - Unarchive Technical Record
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      requestBody:
        description: The desired status code of the new technical record and the reason for the unarchival
        content:
          application/json:
            schema:
              type: object
              required: [status, reasonForUnarchiving]
              properties:
                status:
                  type: string
                reasonForUnarchiving:
                  type: string
      responses:
        '200':
          description: Returns the unarchived technical record with the supplied status
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
        '422':
          description: Unprocessable request
        '500':
          description: Validation Error
  '/v3/technical-records/adrCertificate/{systemNumber}/{createdTimestamp}':
    post:
      summary: 'Generate a new ADR certificate for specific technical record'
      tags:
        - Generate a ADR Certificate
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - certificateType
              properties:
                certificateType:
                  type: string
      responses:
        '200':
          description: Returns the new certificate id with the supplied status
          content:
            application/json:
              schema:
                type: object
                required: [message, id]
                properties:
                  message:
                    type: string
                  id:
                    type: string
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
        '422':
          description: Unprocessable request
        '500':
          description: Validation Error
  '/v3/technical-records/updateVrm/{systemNumber}/{createdTimestamp}':
    patch:
      summary: 'Update VRM on a technical record'
      tags:
        - Update VRM
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
            minLength: 3
            maxLength: 21
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
            pattern: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{0,20}Z
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      operationId: updateVrm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - newVrm
              properties:
                newVrm:
                  type: string
                isCherishedTransfer:
                  type: boolean
                thirdMark:
                  type: string
      responses:
        '200':
          description: Returns the updated technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
  '/v3/technical-records/updateVin/{systemNumber}/{createdTimestamp}':
    patch:
      summary: 'Update VIN on a technical record'
      tags:
        - Update VIN
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
            minLength: 3
            maxLength: 21
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
            pattern: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{0,20}Z
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      operationId: updateVin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - newVin
              properties:
                newVin:
                  type: string
      responses:
        '200':
          description: Returns the complete updated technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
  '/v3/technical-records/plate/{systemNumber}/{createdTimestamp}':
    post:
      summary: 'Generates a plate for a TRL or HGV technical record'
      tags:
        - Generate Plate
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of the Datetime at which the technical record was created. Sort key of the DynamoDB table.
      operationId: plate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - vtmUsername
                - reasonForCreation
                - recipientEmailAddress
              properties:
                vtmUsername:
                  type: string
                recipientEmailAddress:
                  type: string
                reasonForCreation:
                  type: string
                  enum:
                    - 'Free replacement'
                    - 'Replacement'
                    - 'Destroyed'
                    - 'Provisional'
                    - 'Original'
                    - 'Manual'
      responses:
        '200':
          description: Success
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
  '/v3/technical-records/letter/{systemNumber}/{createdTimestamp}':
    post:
      summary: 'Generates a letter for a technical record'
      tags:
        - Generate Letter
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      operationId: letter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - vtmUsername
                - recipientEmailAddress
                - letterType
                - paragraphId
              properties:
                vtmUsername:
                  type: string
                recipientEmailAddress:
                  type: string
                letterType:
                  type: string
                  enum:
                    - 'trailer acceptance'
                    - 'trailer rejection'
                paragraphId:
                  type: number
                  enum:
                   - 3
                   - 4
                   - 5
                   - 6
                   - 7
      responses:
        '200':
          description: Success
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 
  '/v3/technical-records/promote/{systemNumber}/{createdTimestamp}':
    post:
      summary: 'Promotes the specified provisional technical record to current'
      tags:
        - Promote a Technical Record
      parameters:
        - in: path
          name: systemNumber
          schema:
            type: string
          required: true
          description: This represents the systemNumber of the vehicle. Partition key of the DynamoDB table.
        - in: path
          name: createdTimestamp
          schema:
            type: string
          required: true
          description: String representation of a DateTime at which the technical record was created. Sort key of the DynamoDB table.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object 
              required:
                - reasonForPromoting
              properties:
                reasonForPromoting:
                  type: string
      responses:
        '200':
          description: Returns the promoted technical record
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/techRecordGETComplete"
                  - $ref: "#/components/schemas/techRecordGETSkeleton"
                  - $ref: "#/components/schemas/techRecordGETTestable"
        '400':
          description: Bad request
        '401':
          description: Not authenticated
        '403':
          description: Unauthorised Access
        '404':
          description: No records found matching identifier and criteria 

  '/v3/technical-records/recalls/{vin}':
    get:
      summary: 'Brokering API with MOT recalls API'
      tags:
        - Call MOT Recalls
      parameters:
        - in: path
          name: vin
          schema:
            type: string
          required: true
          description: This represents the vin of the vehicle. Used to call MOT Recalls API.
      responses:
        '200':
          description: Returns recall information
          content:
            application/json:
              schema:
                type: object
                properties:
                  manufacturer:
                    type: string
                  hasRecall:
                    type: boolean
        '500':
          description: Internal server error
      
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://example.com/oauth/authorize'
          tokenUrl: 'https://example.com/oauth/token'
          scopes:
            read: Grants read access
            write: Grants write access

  schemas:
    techRecordGETComplete:
      description: schemas for retrievied complete technical records
      oneOf:
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/car/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/lgv/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/motorcycle/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/psv/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/hgv/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/trl/complete/index.json"
    techRecordGETSkeleton:
      oneOf:
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/car/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/lgv/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/motorcycle/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/psv/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/hgv/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/trl/skeleton/index.json"
    techRecordGETTestable:
      oneOf:
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/psv/testable/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/hgv/testable/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/get/trl/testable/index.json"

    techRecordPUTComplete:
      description: schemas for creating and updating complete technical records
      oneOf:
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/car/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/lgv/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/motorcycle/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/psv/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/hgv/complete/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/trl/complete/index.json"
    techRecordPUTSkeleton:
      oneOf:
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/car/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/lgv/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/motorcycle/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/psv/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/hgv/skeleton/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/trl/skeleton/index.json"
    techRecordPUTTestable:
      oneOf:
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/psv/testable/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/hgv/testable/index.json"
        - $ref: "https://raw.githubusercontent.com/dvsa/cvs-type-definitions/v6.4.0/json-schemas/v3/tech-record/put/trl/testable/index.json"


security:
  - OAuth2:
      - read
      - write