Evidence Platform API Swagger

api.yml

openapi: '3.0.0'
info:
  title: Evidence Platform API
  version: 1.0.0
paths:
  /document_types:
    get:
      operationId: get-all-document-types
      summary: Returns all recognised document types
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/document-type'
        401:
          $ref: '#/components/responses/not-authorized'
  /evidence_requests:
    post:
      operationId: create-evidence-request
      summary: Creates a new evidence request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evidence-request-attributes'
              
      responses:
        201:
          description: Saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evidence-request-response'
        400:
          $ref: '#/components/responses/bad-request'
        401:
          $ref: '#/components/responses/not-authorized'
  /evidence_requests/{id}:
    get:
      operationId: get-evidence-request
      summary: Get details of an individual evidence-request
      parameters:
        - name: id
          in: path
          description: Evidence Request ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/evidence-request-response'
        401:
          $ref: '#/components/responses/not-authorized'
        404:
          $ref: '#/components/responses/not-found'

components:
  parameters:
    documentId:
      name: documentId
      in: path
      required: true
      description: The id of the document
      schema:
        type: string

  schemas:
    error:
      type: object
      properties:
        error:
          type: string
          description: A machine readable error code
          example: not_found
        description:
          type: string
          description: A human readable description of the error
          example: Resource not found
    document-type:
      type: object
      properties:
        id:
          type: string
          description: A unique id for the document type
        title:
          type: string
          description: A human-friendly title for the document type
      example:
        {
          "id": "passport-scan",
          "title": "Passport Scan"
        }
    resident:
      type: object
      properties:
        name:
          type: string
          description: "The resident's name"
          example: "Frodo Baggins"
        email:
          type: string
          format: email
          description: "The resident's email address"
          example: "[email protected]"
        phone_number:
          type: string
          description: "The resident's email address"
          example: "+447123456780"
    evidence-request-attributes:
      type: object
      required:
        - resident
        - document_type
      properties:
        resident:
          $ref: '#/components/schemas/resident'
        delivery_methods:
          type: array
          default: ["sms", "email"]
          items:
            type: string
            enum:
              - sms
              - email
        document_type:
          type: string
          example: "passport_scan"
        service_requested_by:
          type: string
          description: The service area (currently Google Group) which this requests document
          example: development-team-staging
    evidence-request-response:
      type: object
      allOf:
        - properties:
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        - $ref: '#/components/schemas/evidence-request-attributes'
      
  responses:
    not-found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            {
              "error": "not_found",
              "description": "Resource not found"
            }
    bad-request:
      description: Request contains invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            {
              "error": "bad_request",
              "description": "Request contains invalid parameters"
            }
    not-authorized:
      description: Request lacks valid API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            {
              "error": "not_authorized",
              "description": "Request lacks valid API token"
            }