Tern REST API Design Doc

[nishakm]

Relates to issue tern-tools/tern#1112 and super issue tern-tools/tern#1110

The task is to create an API Design Doc.

[nishakm]

Here is a Swagger YAML I constructed using editor.swagger.io:

swagger: "2.0"
info:
  description: "Tern is a software composition analysis tool and Python library that generates a Software Bill of Materials for container images and Dockerfiles. The SBOM that Tern generates will give you a layer-by-layer view of what's inside your container in a variety of formats including human-readable, JSON, HTML, SPDX and more."
  version: "1.0.0"
  title: "Tern Kubernetes Service"
  license:
    name: "BSD-2-Clause"
    url: "https://github.com/tern-tools/tern-api/blob/main/LICENSE.txt"
basePath: "/v1"
schemes:
- "https"
paths:
  /image/repo-tag:
    get:
      tags:
      - "image"
      summary: "Analyze an image by its repository name and tag or repository name and digest"
      description: "Provide the image string domain/org/repo:tag or domain/org/repo@digest_type:digest"
      operationId: "analyzeImage"
      produces:
      - "application/json"
      parameters:
      - name: "format"
        in: "query"
        description: "Return the results in a format. No parameters returns the default JSON format"
        required: false
        type: "string"
        enum:
          - "spdx"
          - "cyclonedx"
      responses:
        "200":
          description: "OK"
          schema:
            type: "object"
        "400":
          description: "Bad Request"
        "404":
          description: "Not Found"

[nishakm]

Here is an OpenAPI3 conformant layout:

openapi: 3.0.1
info:
  title: Tern Kubernetes Service
  description: Tern is a software composition analysis tool and Python library that
    generates a Software Bill of Materials for container images and Dockerfiles. The
    SBOM that Tern generates will give you a layer-by-layer view of what's inside
    your container in a variety of formats including human-readable, JSON, HTML, SPDX
    and more.
  license:
    name: BSD-2-Clause
    url: https://github.com/tern-tools/tern-api/blob/main/LICENSE.txt
  version: 1.0.0
servers:
- url: /v1
paths:
  /image/repo-tag:
    get:
      tags:
      - image
      summary: Analyze an image by its repository name and tag or repository name
        and digest
      description: Provide the image string domain/org/repo:tag or domain/org/repo@digest_type:digest
      operationId: analyzeImage
      parameters:
      - name: format
        in: query
        description: Return the results in a format. No parameters returns the default
          JSON format
        schema:
          type: string
          enum:
          - spdx
          - cyclonedx
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
        400:
          description: Bad Request
          content: {}
        404:
          description: Not Found
          content: {}
components: {}