api.yaml

openapi: 3.1.1

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: tagop
          description: Operator to use for matching tags.
          schema:
            type: string
            enum: ["and", "or"]
        - 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/scorecard:
    get:
      summary: Returns an image's OpenSSF scorecard report
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The image's OpenSSF scorecard report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageScorecard"

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

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

  /image/vulnerabilities:
    get:
      summary: Returns an image's vulnerabilities
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The image's vulnerabilitiess
          content:
            application/json:
              schema:
                type: object
                properties:
                  vulnerabilities:
                    type: array
                    items:
                      $ref: "https://raw.githubusercontent.com/ossf/osv-schema/main/validation/schema.json"

  /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"

  /image/logo:
    get:
      summary: Returns the logo of the image or an external link to it
      parameters:
        - in: query
          name: reference
          schema:
            type: string
          required: true
      responses:
        "200":
          description: The image's logo
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/svg+xml:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        "307":
          description: The image is found at an external URL
          headers:
            Location:
              description: The image's external URL
              schema:
                type: string
                format: url
        "404":
          description: Not found

  /events:
    get:
      summary: Server-sent events.
      responses:
        "200":
          description: Server-sent events.
          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

  /images/poll:
    post:
      summary: Poll available images from the platform in use.
      responses:
        "200":
          description: Images polled successfully

  /feed.rss:
    get:
      summary: Get an RSS feed of outdated images.
      responses:
        "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
        annotations:
          type: object
          additionalProperties:
            type: string
        lasestReference:
          type: string
          description: The latest available version on the same track
        latestCreated:
          type: string
          format: datetime
        latestAnnotations:
          type: object
          additionalProperties:
            type: string
        tags:
          type: array
          items:
            type: string
        links:
          type: array
          items:
            $ref: "#/components/schemas/ImageLink"
        vulnerabilities:
          type: number
        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
        - vulnerabilities
        - 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

    ImageScorecard:
      type: object
      description: An OpenSSF scorecard report
      properties:
        reportUrl:
          type: string
          format: url
          description: URL to full report
        score:
          type: number
          description: Score 0-10 where higher is better
        risk:
          type: string
          enum: ["critical", "high", "medium", "low"]
        generatedAt:
          type: string
          format: date
      required:
        - reportUrl
        - score
        - risk
        - generatedAt

    ImageProvenance:
      type: object
      description: Provenance
      properties:
        buildInfo:
          type: array
          items:
            $ref: "#/components/schemas/ProvenanceBuildInfo"
      required:
        - buildInfo

    ProvenanceBuildInfo:
      type: object
      description: Build info
      properties:
        imageDigest:
          type: string
        architecture:
          type: string
        architectureVariant:
          type: string
        operatingSystem:
          type: string
        source:
          type: string
        sourceRevision:
          type: string
        buildStartedOn:
          type: string
          format: date
        buildFinishedOn:
          type: string
          format: date
        dockerfile:
          type: string
        buildArguments:
          type: object
          additionalProperties:
            type: string
      required:
        - imageDigest

    ImageSBOM:
      type: object
      description: SBOM
      properties:
        sbom:
          type: array
          items:
            $ref: "#/components/schemas/SBOM"
      required:
        - sbom

    SBOM:
      type: object
      description: SBOM
      properties:
        imageDigest:
          type: string
        # TODO: In v1, change name to predicateType and just keep the predicate
        # type from the registry
        type:
          type: string
          enum:
            - spdx
        sbom:
          type: string
        architecture:
          type: string
        architectureVariant:
          type: string
        operatingSystem:
          type: string
      required:
        - imageDigest
        - type
        - sbom

    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
        internalLabels:
          type: object
          additionalProperties:
            type: string
      required:
        - domain
        - type
        - name

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

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

    PlatformEvent:
      type: object
      properties:
        type:
          type: string
          enum: ["graphUpdated"]

    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