openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: kusk-gateway-api
  description: "This is the Kusk Gateway Management API"
servers:
  - url: http://localhost:8080
    description: "My local endpoint mockup"
externalDocs:
  description: "Find out more about Kusk-Gateway"
  url: "https://kubeshop.github.io/kusk-gateway/"
tags:
  - name: "apis"
    description: "Get the list of the APIs"
  - name: "services"
    description: "Get the list of all services"
  - name: "fleets"
    description: "Get the list of all envoy fleets"
  - name: "static routes"
    description: "Get the list of all static routes"
x-kusk:
  upstream:
    service:
      name: kusk-gateway-api
      namespace: kusk-system
      port: 80
    rewrite:
      pattern: "^/api"
      substitution: ""
  path:
    prefix: /api
paths:
  /apis:
    get:
      tags:
        - "apis"
      summary: "Get a list of APIs"
      description: "Returns the list of APIs available in the cluster"
      operationId: getApis
      parameters:
        - name: fleetname
          in: query
          schema:
            type: string
          required: false
          description: optional filter on fleet
        - name: fleetnamespace
          in: query
          schema:
            type: string
          required: false
          description: optional filter on fleet
        - name: namespace
          in: query
          schema:
            type: string
          required: false
          description: optional filter on namespace
      responses:
        200:
          description: a list of apis
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiItem"
    post:
      tags:
        - "apis"
      summary: "Deploy new API"
      description: "Deploys a new API to the cluster"
      operationId: deployApi
      requestBody:
        description: "API content that needs to be deployed"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                namespace:
                  type: string
                envoyFleetName:
                  type: string
                envoyFleetNamespace:
                  type: string
                openapi:
                  type: string
      responses:
        201:
          description: "API deployed"
        400:
          description: "The content of the API is malformed"
          content:
            application/json:
              schema:
                type: string
  /apis/{namespace}/{name}:
    get:
      tags:
        - "apis"
      summary: "Get an API instance by namespace and name"
      operationId: getApi
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "API item"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiItem"
        404:
          description: "API item not found"
    put:
      tags:
        - "apis"
      summary: "Update an existing API"
      description: "Updates an existing API in the cluster"
      operationId: updateApi
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: "API content that needs to be updated"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                namespace:
                  type: string
                envoyFleetName:
                  type: string
                envoyFleetNamespace:
                  type: string
                openapi:
                  type: string
      responses:
        201:
          description: "API deployed"
        400:
          description: "The content of the API is malformed"
          content:
            application/json:
              schema:
                type: string
        404:
          description: "API not found"
    delete:
      tags:
        - "apis"
      summary: "Delete an API instance by namespace and name"
      operationId: deleteApi
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: "api item deleted"
        404:
          description: "api item not found"
  /apis/{namespace}/{name}/crd:
    get:
      tags:
        - "apis"
      summary: "Get API CRD from cluster"
      operationId: getApiCRD
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "returns the CRD of the API ( Raw Api Spec )"
          content:
            application/json:
              schema:
                type: object
        404:
          description: "API CRD not found"
  /apis/{namespace}/{name}/definition:
    get:
      tags:
        - "apis"
      summary: "Get API definition ( Post-Processed version )"
      operationId: getApiDefinition
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "API definition item"
          content:
            application/json:
              schema:
                type: object
        404:
          description: "API definition not found"
  /services:
    get:
      tags:
        - "services"
      summary: "Get a list of services handled by kusk-gateway"
      description: "Returns the list of services available in the cluster that are related to kusk-gateway"
      operationId: getServices
      parameters:
        - name: namespace
          in: query
          schema:
            type: string
          required: false
          description: optional filter on namespace
      responses:
        200:
          description: list of services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ServiceItem"
  /services/{namespace}/{name}:
    get:
      tags:
        - "services"
      summary: "Get details for a single service"
      description: "Returns an object containing info about the service corresponding to the namespace and name"
      operationId: getService
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: service details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceItem"
        404:
          description: "Service not found by namespace-name combination"
  /fleets:
    get:
      tags:
        - "fleets"
      summary: "Get a list of envoy fleets"
      description: "Returns a list of envoy fleets that are available in the cluster"
      operationId: getEnvoyFleets
      parameters:
        - name: namespace
          in: query
          schema:
            type: string
          required: false
          description: optional filter on namespace
      responses:
        200:
          description: list of envoy fleets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EnvoyFleetItem"
    post:
      tags:
        - "create new fleet"
      summary: "create new fleet"
      operationId: createFleet
      requestBody:
        description: "create fleet content"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceItem"
      responses:
        200:
          description: "created fleet"
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/EnvoyFleetItem"
        400:
          description: "The content of the API is malformed"
          content:
            application/json:
              schema:
                type: string
  /fleets/{namespace}/{name}:
    get:
      tags:
        - "fleets"
      summary: "Get details for a single envoy fleet"
      description: "Returns an object containing info about the envoy fleet corresponding to the namespace and name"
      operationId: getEnvoyFleet
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
          description: the namespace of the fleet
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: the name of the fleet
      responses:
        200:
          description: envoy fleet details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvoyFleetItem"
        404:
          description: "Envoy fleet not found by namespace-name combination"
    delete:
      tags:
        - "fleets"
      summary: "Delete a Fleet instance by namespace and name"
      operationId: deleteFleet
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: "fleet item deleted"
        404:
          description: "fleet item not found"
  /fleets/{namespace}/{name}/crd:
    get:
      tags:
        - "fleets"
      summary: "Get envoy fleet CRD"
      operationId: getEnvoyFleetCRD
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Envoy fleet CRD"
          content:
            application/json:
              schema:
                type: object
        404:
          description: "Envoy fleet CRD not found"
  /logs:
    x-kusk:
      upstream:
        service:
          name: kusk-gateway-api
          namespace: kusk-system
          port: 8081
        rewrite:
          pattern: "^/api"
          substitution: ""
      websocket: true
    get:
      tags:
        - "fleets"
      summary: "Get envoy fleet logs"
      operationId: getEnvoyFleetLogs
      parameters:
        - name: namespace
          in: query
          required: true
          schema:
            type: string
            default: "kusk-system"
        - name: name
          in: query
          required: true
          schema:
            type: string
            default: "kusk-gateway-envoy-fleet"
      responses:
        200:
          description: "Envoy fleet logs"
          content:
            application/json:
              schema:
                type: object
        404:
          description: "Envoy fleet logs not found"

  /staticroutes:
    get:
      tags:
        - "static routes"
      summary: "Get a list of static routes"
      description: "Returns a list of static routes"
      operationId: getStaticRoutes
      parameters:
        - name: namespace
          in: query
          schema:
            type: string
          required: false
          description: "optional filter on namespace"
      responses:
        200:
          description: "list of static routes"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/StaticRouteItem"
    post:
      tags:
        - "create new static route"
      summary: "create new static route"
      operationId: createStaticRoute
      requestBody:
        description: "static route content"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                namespace:
                  type: string
                envoyFleetName:
                  type: string
                envoyFleetNamespace:
                  type: string
                openapi:
                  type: string

      responses:
        200:
          description: "created static route"
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/StaticRouteItem"
        400:
          description: "The content of the API is malformed"
          content:
            application/json:
              schema:
                type: string
  /staticroutes/{namespace}/{name}:
    get:
      tags:
        - "static routes"
      summary: "Get details for a single static route"
      description: "Returns an object containing info about the static route corresponding to the namespace and name"
      operationId: getStaticRoute
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
          description: "the namespace of the static route"
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: "the name of the static route"
      responses:
        200:
          description: "get static route details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StaticRouteItem"
        404:
          description: "Static Route not found by namespace-name combination"
    put:
      tags:
        - "static routes"
      summary: "Update a static route by namespace and name"
      operationId: "updateStaticRoute"
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: "static route content"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                namespace:
                  type: string
                envoyFleetName:
                  type: string
                envoyFleetNamespace:
                  type: string
                openapi:
                  type: string
      responses:
        201:
          description: "static route updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StaticRouteItem"
        400:
          description: "The content of the static route is malformed"
          content:
            application/json:
              schema:
                type: string
        404:
          description: "static route not found"
    delete:
      tags:
        - "static Route"
      summary: "Delete a StaticRoute by namespace and name"
      operationId: deleteStaticRoute
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        204:
          description: "staticRoute item deleted"
        404:
          description: "staticRoute item not found"
  /staticroutes/{namespace}/{name}/crd:
    get:
      tags:
        - "static routes"
      summary: "Get static route CRD"
      operationId: getStaticRouteCRD
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
            default: "default"
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Static route CRD"
          content:
            application/json:
              schema:
                type: object
        404:
          description: "Static route CRD not found"
  /namespaces:
    get:
      tags:
        - "namespaces"
      summary: "Get a list of namespaces"
      description: "Returns a list of namespaces"
      operationId: getNamespaces
      responses:
        200:
          description: "list of namespaces"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NamespaceItem"
components:
  schemas:
    ApiItem:
      type: object
      required:
        - name
        - namespace
        - fleet
        - service
        - version
      properties:
        name:
          type: string
        namespace:
          type: string
        fleet:
          $ref: "#/components/schemas/ApiItem_Fleet"
        service:
          $ref: "#/components/schemas/ApiItem_Service"
        version:
          type: string
        crunch42url:
          type: string
    ServiceItem:
      type: object
      required:
        - name
        - namespace
        - serviceType
        - ports
      properties:
        name:
          type: string
        status:
          type: string
          enum:
            - available
            - unavailable
        namespace:
          type: string
        serviceType:
          type: string
          enum:
            - ClusterIP
            - LoadBalancer
        ports:
          type: array
          items:
            $ref: "#/components/schemas/ServicePortItem"
    EnvoyFleetItem:
      type: object
      required:
        - name
        - namespace
      properties:
        name:
          type: string
        namespace:
          type: string
        apis:
          type: array
          items:
            $ref: "#/components/schemas/ApiItem_Fleet"
        services:
          type: array
          items:
            $ref: "#/components/schemas/ServiceItem"
        staticRoutes:
          type: array
          items:
            $ref: "#/components/schemas/StaticRouteItem_Fleet"
    StaticRouteItem:
      type: object
      required:
        - name
        - namespace
      properties:
        name:
          type: string
        namespace:
          type: string
        envoyFleetName:
          type: string
        envoyFleetNamespace:
          type: string
    ApiItem_Fleet:
      type: object
      required:
        - name
        - namespace
      properties:
        name:
          type: string
        namespace:
          type: string
    ServicePortItem:
      type: object
      required:
        - name
        - port
        - targetPort
      properties:
        name:
          type: string
        nodePort:
          type: integer
        port:
          type: integer
        protocol:
          type: string
        targetPort:
          type: string
    StaticRouteItem_Fleet:
      type: object
      required:
        - name
        - namespace
      properties:
        name:
          type: string
        namespace:
          type: string
    ApiItem_Service:
      type: object
      required:
        - name
        - namespace
      properties:
        name:
          type: string
        namespace:
          type: string
    NamespaceItem:
      type: object
      properties:
        name:
          type: string