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:
                $ref: '#/components/schemas/Tag'

  /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: Property to sort by.
          schema:
            type: string
            enum: ['reference']
          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.
          schema:
            type: integer
          required: false
        - in: query
          name: limit
          description: Page size limit for pagination.
          schema:
            type: integer
          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'

components:
  schemas:
    Tag:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        color:
          type: string

    ImagePage:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        summary:
          type: object
          properties:
            images:
              description: Total number of images
              type: number
            outdated:
              description: Total number of outdated images
              type: number
            processing:
              description: Total number of unprocessed images
              type: number
          required:
            - images
            - outdated
            - pods
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
      required:
        - images
        - summary
        - pagination

    PaginationMetadata:
      type: object
      properties:
        total:
          description: Total entries.
          type: integer
        page:
          description: Page index.
          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
        description:
          type: string
        lasestReference:
          type: string
          description: The latest available version on the same track
        tags:
          type: array
          items:
            type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/ImageLink'
        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

    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
      required:
        - domain
        - type
        - name