openapi: 3.0.1
info:
  title: DVSA - Vehicle Recalls Service API
  version: 2.8.0
servers:
  - url: https://manufacturer.vehicle-recalls.api.gov.uk/v1
    description: Base URL
security:
  - AuthoriserLambda: []
  - api_key: []
paths:
  /recalls:
    post:
      tags:
        - recalls
      summary: Create a new recall for a single vehicle
      requestBody:
        description: Recall details
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRecallRequestBody"
      responses:
        "201":
          $ref: "#/components/responses/201Created"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "409":
          $ref: "#/components/responses/409Conflict"
        "500":
          $ref: "#/components/responses/500InternalServerError"
      security:
        - AuthoriserLambda: []
        - api_key: []
  "/recalls/vin/{vin}":
    get:
      tags:
        - recalls
      summary: Get all recall information for a single vehicle
      parameters:
        - $ref: "#/components/parameters/vin"
        - $ref: "#/components/parameters/manufacturerCampaignReference"
        - $ref: "#/components/parameters/dvsaCampaignReference"
      responses:
        "200":
          $ref: "#/components/responses/200OkResource"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "500":
          $ref: "#/components/responses/500InternalServerError"
      security:
        - AuthoriserLambda: []
        - api_key: []
    put:
      tags:
        - recalls
      summary: Update a vehicle's recall status
      requestBody:
        description: Recalls details
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRecallRequestBody"
      parameters:
        - $ref: "#/components/parameters/vin"
        - $ref: "#/components/parameters/manufacturerCampaignReference"
        - $ref: "#/components/parameters/dvsaCampaignReference"
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "500":
          $ref: "#/components/responses/500InternalServerError"
      security:
        - AuthoriserLambda: []
        - api_key: []
    delete:
      tags:
        - recalls
      summary: Delete a recall for a single vehicle
      parameters:
        - $ref: "#/components/parameters/vin"
        - $ref: "#/components/parameters/manufacturerCampaignReference"
        - $ref: "#/components/parameters/dvsaCampaignReference"
      responses:
        "204":
          $ref: "#/components/responses/204NoContent"
        "400":
          $ref: "#/components/responses/400BadRequest"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "404":
          $ref: "#/components/responses/404NotFound"
        "500":
          $ref: "#/components/responses/500InternalServerError"
      security:
        - AuthoriserLambda: []
        - api_key: []
  /credentials:
    put:
      tags:
        - recalls
      summary: Request a new client secret
      description: |-
        PUT: /credentials

        Request a new client secret
      responses:
        "200":
          $ref: "#/components/responses/CredentialResponse"
        "401":
          $ref: "#/components/responses/401Unauthorized"
        "403":
          $ref: "#/components/responses/403Forbidden"
        "500":
          $ref: "#/components/responses/500InternalServerError"
      security:
        - AuthoriserLambda: []
        - api_key: []
components:
  responses:
    200OkResource:
      description: Vehicle recall object with vin
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RecallResponse"
    201Created:
      description: Recall created successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreatedRecallResponse"
    204NoContent:
      description: No Content
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdatedResponse"
    400BadRequest:
      description: The format of the request is incorrect
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/400Error"
    404NotFound:
      description: The requested data is not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/404Error"
    401Unauthorized:
      description: The authorization headers in the request are missing or incorrect
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/401Error"
    403Forbidden:
      description: The user is not allowed to access the resource or manufacturer is
        disabled
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/403Error"
    409Conflict:
      description: Recall is already registered
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/409Error"
    500InternalServerError:
      description: An unexpected error has occurred
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/500Error"
    CredentialResponse:
      description: Successfully renew API credentials and returns new client secret
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RenewedCredentialResponse"
  schemas:
    ErrorResponse:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          description: Code to identify the type of error. See "Error Codes" in API
            documentation for detail on each code.
          type: string
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
    400Error:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          default: 400
          type: number
          description: Code to identify the type of error.
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
          default: Bad Request
    404Error:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          default: 404
          type: number
          description: Code to identify the type of error.
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
          default: Not Found
    409Error:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          default: 409
          type: number
          description: Code to identify the type of error.
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
          default: Conflict
    401Error:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          default: 401
          type: number
          description: Code to identify the type of error.
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
          default: Unauthorized
    403Error:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          default: 403
          type: number
          description: Code to identify the type of error.
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
          default: Forbidden
    500Error:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
        errorCode:
          default: 500
          type: number
          description: Code to identify the type of error.
        errorMessage:
          description: Contains additional details about the error of the operation
          maxLength: 4096
          type: string
          default: Internal Server Error
    UpdatedResponse:
      type: object
      properties:
        statusCode:
          type: number
          default: 204
        message:
          type: string
          default: No Content
    CreateRecallRequestBody:
      type: object
      properties:
        vin:
          type: string
          description: Vehicle Identification Number
          example: 1GNEK13ZX3R298984
          nullable: false
        manufacturerCampaignReference:
          type: string
          example: ABCCARS/1
          nullable: false
          minLength: 1
          maxLength: 50
          description: "- Allowed characters: a-z, A-Z, 0-9, -, _, /, \\\\"
        dvsaCampaignReference:
          type: string
          example: DVSA/ABCCARS-1
          nullable: true
          maxLength: 50
          description: "- Allowed characters: a-z, A-Z, 0-9, -, _, /, \\\\"
        recallCampaignStartDate:
          type: string
          format: date
          nullable: false
          description: "- Format: YYYY-MM-DD"
    UpdateRecallRequestBody:
      type: object
      properties:
        repairStatus:
          nullable: false
          type: string
          enum:
            - FIXED
            - NOT_FIXED
        rectificationDate:
          nullable: true
          type: string
          format: date
          description: "- Format: YYYY-MM-DD"
    VIN:
      type: string
      description: Vehicle Identification Number
      example: 1GNEK13ZX3R298984
    CampaignReference:
      type: string
      description: Recall Reference Number
      example: ABCCARS/001
    RecallResponse:
      type: object
      properties:
        vin:
          type: string
          example: 1GNEK13ZX3R298984
          nullable: false
        manufacturer:
          type: string
          example: ABCCARS
          nullable: false
        recalls:
          type: array
          items:
            type: object
            properties:
              manufacturerCampaignReference:
                type: string
                example: ABCCARS/1
                nullable: false
              dvsaCampaignReference:
                type: string
                example: DVSA/ABCCARS-1
                nullable: false
              recallCampaignStartDate:
                type: string
                format: date
                nullable: true
                description: |
                  - Format: YYYY-MM-DD
              repairStatus:
                type: string
                enum:
                  - FIXED
                  - NOT_FIXED
                nullable: false
        lastUpdatedDate:
          type: string
          format: date
          nullable: true
          description: |
            - Format: YYYY-MM-DD
    CreatedRecallResponse:
      type: object
      properties:
        manufacturer:
          type: string
          example: ABCCARS
          nullable: false
        recall:
          type: object
          properties:
            vin:
              type: string
              example: 1GNEK13ZX3R298984
              nullable: false
            manufacturerCampaignReference:
              type: string
              example: ABCCARS/1
              nullable: false
            dvsaCampaignReference:
              type: string
              example: DVSA/ABCCARS-1
              nullable: false
            recallCampaignStartDate:
              type: string
              format: date
              nullable: true
              description: |
                - Format: YYYY-MM-DD
    RenewedCredentialResponse:
      type: object
      properties:
        clientSecret:
          type: string
          example: your-new-client-secret-value
          nullable: false
  parameters:
    vin:
      name: vin
      in: path
      required: true
      description: Vehicle Identification Number
      style: simple
      schema:
        $ref: "#/components/schemas/VIN"
    manufacturerCampaignReference:
      name: manufacturerCampaignReference
      in: query
      description: Recall Reference
      schema:
        $ref: "#/components/schemas/CampaignReference"
    dvsaCampaignReference:
      name: dvsaCampaignReference
      in: query
      description: Recall Reference
      schema:
        $ref: "#/components/schemas/CampaignReference"
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
    AuthoriserLambda:
      type: http
      scheme: bearer
      description: "- Format: `Bearer {JWT Token}`"
      bearerFormat: JWT
      x-amazon-apigateway-authtype: custom
