api.yaml

openapi: 3.1.0

info:
  title: Cupdate
  version: "1.0"

servers:
  - url: http://localhost:8080/api/v1

paths:
  /tags:
    get:
      summary: Returns available tags.
    responses:
      "200":
        description: A list of tags.
        content:
          application/json:
            schema:
              type: array
              items:
                type: string

  /images:
    get:
      summary: Returns a paginated list of images.
      parameters:
        - in: query
          name: tag
          description: Tag to filter by. May occur more than once.
          schema:
            type: string
          required: false
        - in: query
          name: sort
          description: Sort type.
          schema:
            type: string
            enum: ["reference", "bump"]
          required: false
        - in: query
          name: order
          description: Order to sort by.
          schema:
            type: string
            enum: ["asc", "desc"]
        - in: query
          name: page
          description: Page to view. Indexes start at 1.
          schema:
            type: integer
          required: false
        - in: query
          name: limit
          description: Page size limit for pagination.
          schema:
            type: integer
          required: false
        - in: query
          name: query
          description: Full text search query.
          schema:
            type: string
          required: false
      responses:
        "200":
          description: A page of images.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImagePage"

  /image:
    get:
      summary: Returns an image.
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: An image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Image"

  /image/description:
    get:
      summary: Returns an image's description.
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Rendered HTML description of the image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageDescription"
        "404":
          description: No description was found

  /image/release-notes:
    get:
      summary: Returns an image's release notes.
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Description of the version's release notes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageReleaseNotes"
        "404":
          description: No release notes were found

  /image/graph:
    get:
      summary: Returns an image's graph
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The image's graph
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Graph"

  /image/workflows/latest:
    get:
      summary: Returns an image's latest workflow run
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The latest workflow run for the image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRun"

  /events:
    get:
      summary: Server-sent events.
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/Event"

  # TODO: This API is rather simplified. Perhaps we should expose more internals
  # like processing logs, time to process etc.
  /image/scans:
    post:
      summary: Schedule a new scan.
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "201":
          description: Accepted

  /feed.rss:
    get:
      summary: Get an RSS feed of outdated images.
      respones:
        "200":
          description: RSS feed.
          content:
            application/rss+xml:

  /summary:
    get:
      summary: Get a summary.
      responses:
        "200":
          description: Summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Summary"

components:
  schemas:
    ImagePage:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: "#/components/schemas/Image"
        summary:
          $ref: "#/components/schemas/Summary"
        pagination:
          $ref: "#/components/schemas/PaginationMetadata"
      required:
        - images
        - summary
        - pagination

    PaginationMetadata:
      type: object
      properties:
        total:
          description: Total entries.
          type: integer
        page:
          description: Page index. Indexes start at 1.
          type: integer
        size:
          description: Requested page size.
          type: integer
        next:
          type: string
        previous:
          type: string
      required:
        - total
        - page
        - size

    Image:
      type: object
      properties:
        reference:
          type: string
        created:
          type: string
          format: datetime
        description:
          type: string
        lasestReference:
          type: string
          description: The latest available version on the same track
        latestCreated:
          type: string
          format: datetime
        tags:
          type: array
          items:
            type: string
        links:
          type: array
          items:
            $ref: "#/components/schemas/ImageLink"
        vulnerabilities:
          type: array
          items:
            $ref: "#/components/schemas/ImageVulnerability"
        lastModified:
          type: string
          format: datetime
          description: When the image's information was last updated
        image:
          type: string
          format: url
          description: URL to an image
      required:
        - reference
        - tags
        - links
        - lastModified

    ImageDescription:
      type: object
      properties:
        html:
          type: string
        markdown:
          type: string

    ImageReleaseNotes:
      type: object
      properties:
        title:
          type: string
        html:
          type: string
        markdown:
          type: string
        released:
          type: string
          format: date
      required:
        - title

    ImageLink:
      type: object
      properties:
        type:
          type: string
          example: github
        url:
          type: string
          format: url
      required:
        - type
        - url

    ImageVulnerability:
      type: object
      properties:
        severity:
          type: string
          enum: ["critical", "high", "medium", "low", "unspecified"]
        authority:
          type: string
          example: Docker Scout
        links:
          type: array
          items:
            type: string
            format: url
        description:
          type: string
          example: CVE-2024-9476
      required:
        - id
        - severity
        - authority
        - links

    Graph:
      type: object
      description: A graph explaining why the image is used.
      properties:
        edges:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: boolean
        nodes:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/GraphNode"
      required:
        - edges
        - nodes

    GraphNode:
      type: object
      properties:
        domain:
          type: string
          example: kubernetes
        type:
          type: string
          example: apps/v1/deploymentset
        name:
          type: string
          example: default
        labels:
          type: object
          additionalProperties:
            type: string
      required:
        - domain
        - type
        - name

    Event:
      type: object
      oneOf:
        - $ref: "#/components/schemas/ImageEvent"

    ImageEvent:
      type: object
      properties:
        reference:
          type: string
        type:
          type: string
          enum: ["imageUpdated", "imageProcessed", "imageNewVersionAvailable"]

    Summary:
      type: object
      properties:
        images:
          description: Total number of images
          type: number
        outdated:
          description: Total number of outdated images
          type: number
        vulnerable:
          description: Total number of vulnerable images
          type: number
        # TODO in v1: rename this to "unprocessed"
        # TODO in v1: expose actual queue size from worker queue?
        processing:
          description: Total number of unprocessed images
          type: number
        failed:
          description: Total number of failed images
          type: number
      required:
        - images
        - outdated
        - vulnerable
        - processing
        - failed

    WorkflowRun:
      type: object
      properties:
        started:
          type: string
          format: datetime
        duration:
          type: number
        result:
          type: string
          enum: ["succeeded", "failed"]
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/JobRun"
        traceId:
          type: string
      required:
        - started
        - duration
        - result
        - jobs

    JobRun:
      type: object
      properties:
        result:
          type: string
          enum: ["succeeded", "skipped", "failed"]
        steps:
          type: array
          items:
            $ref: "#/components/schemas/StepRun"
        dependsOn:
          type: array
          items:
            type: string
        jobId:
          type: string
        jobName:
          type: string
        started:
          type: string
          format: datetime
          description: Set if job was run (not skipped).
        duration:
          type: number
          description: Set if job was run (not skipped).
      required:
        - result
        - steps
        - dependsOn

    StepRun:
      type: object
      properties:
        result:
          type: string
          enum: ["succeeded", "skipped", "failed"]
        stepName:
          type: string
        started:
          type: string
          format: datetime
          description: Set if step was run (not skipped).
        duration:
          type: number
          description: Set if step was run (not skipped).
        error:
          type: string
          description: Set if step failed.
      required:
        - result