openapi: 3.0.3
info:
  title: Remote Engine API
  description: |
    <a href="/openapi/wcg/remote-engine-openapi.yaml" target="_blank" download="remote-engine-openapi.yaml"><button>Download OpenAPI Specification</button></a>

    A **Remote Engine** is a service responsible to manage requests from the Witboost Computational Governance to validate resources.

    By implementing this API contract, the service will be able to receive requests to evaluate resources and return the result of the evaluation compliant to the Witboost Computational Governance results. 

    This gives developers the possibility to implement their own validation logic with any technology of their choice, as long as it respects the API contract.

    # Register a Remote Engine

    Once you develop and deploy a microservice that implements the Remote Engine API, when you create a policy or metric in Witboost, you can select the Remote Engine to use for the evaluation.

    When you select Remote Engine, you will be able to provide the URL of the service that implements this API contract. Make sure the service is reachable by the Witboost platform.
  version: "0.1.0"
tags:
  - name: RemoteEngine
paths:
  /v1/evaluate:
    post:
      tags:
        - RemoteEngine
      summary: Evaluate a resource
      description: |
        Computes a result based on the input resource. The result can be a policy result or a metric result.
      operationId: evaluateResource
      requestBody:
        description: An object containing the resource to evaluate using this executor
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InputResource"
            examples:
              systemResource:
                value:
                  content: "apiVersion: v1\nkind: System\nmetadata:\n  name: my-system\n  namespace: my-namespace\n  labels:\n    app: my-app"
                  resourceType: system
                  resourceId: 123456
              s3Resource:
                value:
                  content: arn:aws:s3:::my-bucket
                  resourceType: s3
                  resourceId: 123456
        required: true
      responses:
        200:
          description: Return a response containing the evaluation result
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/PolicyResult"
                  - $ref: "#/components/schemas/MetricResult"
              examples:
                policyResult:
                  value:
                    satisfiesPolicy: false
                    errors:
                      - The S3 object specified at 'specific.s3-arn' does not exist. Expected an existing S3 storage.
                    details:
                      s3Arn: arn:aws:s3:::my-bucket
                metricResult:
                  value:
                    value: 89
                    details:
                      score: 89
                      drop: 11
                    errors:
                      - "There is a drop in descriptor completeness score of about 11%"
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalidInput:
                  value:
                    error: "Invalid input. The resource type 'system' is not supported."
        500:
          description: System problem
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                systemProblem:
                  value:
                    error: "Internal server error. Please try again later."
components:
  schemas:
    InputResource:
      required:
        - content
        - resourceType
        - resourceId
      type: object
      properties:
        content:
          description: |
            The content of the resource to be evaluated. The content can be any type of data, such as a JSON object, a string, a number, etc but always in its string representation. e.g. For a system resource, the content will be a stringified YAML descriptor.
          type: string
        resourceType:
          description: Resource type that is being sent in the content. This has to be agreed between the Remote Engine implementation and the platform's registered resource types.
          type: string
        resourceId:
          description: A unique Resource Identifier inside the Witboost platform.
          type: string
    MetricResult:
      type: object
      required:
        - value
      properties:
        value:
          type: number
          description: A Metric value
          example: 100
        details:
          type: object
          description: A free-form field of additional information linked to the metric result. This will be visible in the Witboost UI as a JSON object.
        errors:
          type: array
          description: A list of errors as a result of a metric computation.
          items:
            type: string
    PolicyResult:
      type: object
      required:
        - satisfiesPolicy
        - errors
      properties:
        satisfiesPolicy:
          type: boolean
          description: Whether the input resource is said to satisfy the policy or not.
        details:
          type: object
          description: A free-form field of additional information linked to the policy result. This will be visible in the Witboost UI as a JSON object.
        errors:
          type: array
          description: A list of errors explaining why the resource is not compliant to the policy.
          items:
            type: string
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string