oar-service-spec.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "oar-service",
    "description": "OAR Test Reporting Ingestion Service",
    "version": "v2",
    "contact": {
      "name": "Ryan",
      "email": "testableproject@gmail.com",
      "url": "https://github.com/ryandem1/oar/"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/ryandem1/oar/blob/main/LICENSE.md"
    }
  },
  "servers": [
    {
      "url": "http://{oarInstance}:{port}",
      "description": "Self-Hosted OAR Instance",
      "variables": {
        "oarInstance": {
          "default": "localhost",
          "description": "The self-hosted instance of the oar-service"
        },
        "port": {
          "enum": [
            "8080",
            "8000",
            "5000",
            "80",
            "443"
          ],
          "default": "8080"
        }
      }
    }
  ],
  "paths": {
    "/test": {
      "post": {
        "summary": "Add new test result",
        "tags": ["Add Result"],
        "description": "Method to add a new test result. Requires a summary/OAR attributes and accepts any arbitrary additional JSON to add to dynamic section of test.",
        "requestBody": {
          "description": "Test details to enrich existing test with",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Test"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully Created, will return ID of the new test result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "integer",
                  "example": 235
                }
              }
            }
          },
          "400": {
            "description": "Error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          }
        },
        "operationId": "post-test"
      }
    },
    "/query": {
      "post": {
        "summary": "Generate test query",
        "description": "Create a base64 encoded test query to represent a batch of tests",
        "tags": ["Generate Query"],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestQuery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Valid query, returns base64 encoded query",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "description": "base64 encoded query string representing a batch of tests."
                }
              }
            }
          },
          "400": {
            "description": "Error generating query string",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          }
        }
      }
    },
    "/tests": {
      "description": "Bulk operations on multiple tests. To interface with multiple tests, pass a valid query to the /query endpoint and use the resulting base64 encoded query string as a parameter for these endpoints.",
      "get": {
        "summary": "Retrieve test results from query",
        "description": "GET test results from a query string",
        "tags": ["Query Operations"],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string",
              "description": "base64 encoded query string obtained from /query"
            },
            "required": false,
            "description": "base64 encoded query string obtained from /query"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "description": "Offset of query"
            },
            "required": false,
            "description": "offset of query"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "description": "limit test results returned"
            },
            "required": false,
            "description": "limit test results returned"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful query response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestQueryResult"
                }
              }
            }
          },
          "400": {
            "description": "Query error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Enrich all test results from query",
        "tags": ["Query Operations"],
        "description": "Enriches test results with new fields, performs a right merge on dynamic attributes.",
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string",
              "description": "base64 encoded query string obtained from /query"
            },
            "required": false,
            "description": "base64 encoded query string obtained from /query"
          }
        ],
        "requestBody": {
          "description": "Test details to enrich existing test with",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Test"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Test successfully enriched"
          },
          "400": {
            "description": "Error enriching test",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete all test results from query",
        "description": "Delete all tests that match the encoded query result obtained from /query",
        "tags": ["Query Operations"],
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string",
              "description": "base64 encoded query string obtained from /query"
            },
            "required": false,
            "description": "base64 encoded query string obtained from /query"
          }
        ],
        "responses": {
          "200": {
            "description": "Delete request was successful and at least 1 test was deleted"
          },
          "304": {
            "description": "Delete request was successful, but there were no test results that matched query."
          },
          "400": {
            "description": "Delete request unsuccessful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientError"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "description": "Get health status of app, like a ICMP echo",
        "summary": "Health status",
        "tags": ["Metadata"],
        "responses": {
          "200": {
            "description": "Healthy response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ClientError": {
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        }
      },
      "HealthStatus": {
        "properties": {
          "health": {
            "type": "string",
            "description": "Health status of app",
            "enum": ["healthy"]
          }
        }
      },
      "Test": {
        "description": "Represents a single test result. Listed is all of the static attributes, but test results can take additional arbitrary JSON that would be stored as unstructured data.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Test ID"
          },
          "summary": {
            "type": "string",
            "description": "Test summary"
          },
          "outcome": {
            "type": "string",
            "enum": ["Passed", "Failed"],
            "description": "Test outcome"
          },
          "analysis": {
            "type": "string",
            "enum": [
              "NotAnalyzed",
              "TruePositive",
              "FalsePositive",
              "TrueNegative",
              "FalseNegative"
            ],
            "description": "Test analysis, typically performed manually after automated outcome."
          },
          "resolution": {
            "type": "string",
            "enum": [
              "Unresolved",
              "NotNeeded",
              "TicketCreated",
              "QuickFix",
              "KnownIssue",
              "TestFixed",
              "TestDisabled"
            ],
            "description": "Resolution for the test result"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "UTC datetime when test was created"
          },
          "modified": {
            "type": "string",
            "format": "date-time",
            "description": "UTC datetime when the test was last modified"
          }
        }
      },
      "TestQuery": {
        "description": "Query object for test results. Values in arrays are treated as logical 'OR's, while multiple arrays are treated as logical 'AND'.",
        "properties": {
          "ids": {
            "type": "array",
            "description": "Pass in an array of test IDs to limit query results to",
            "items": {
              "type": "integer"
            }
          },
          "summaries": {
            "type": "array",
            "description": "Array of partial test summaries to query tests by",
            "items": {
              "type": "string"
            }
          },
          "outcomes": {
            "type": "array",
            "description": "Array of outcomes to search for",
            "items": {
              "type": "string",
              "enum": ["Passed", "Failed"]
            }
          },
          "analyses": {
            "type": "array",
            "description": "Array of analysis values to query for",
            "items": {
              "type": "string",
              "enum": [
                "NotAnalyzed",
                "TruePositive",
                "FalsePositive",
                "TrueNegative",
                "FalseNegative"
              ]
            }
          },
          "resolutions": {
            "type": "array",
            "description": "Array of resolution values to query for",
            "items": {
              "type": "string",
              "enum": [
                "Unresolved",
                "NotNeeded",
                "TicketCreated",
                "QuickFix",
                "KnownIssue",
                "TestFixed",
                "TestDisabled"
              ]
            }
          },
          "createdBefore": {
            "type": "string",
            "format": "date-time",
            "description": "Limit query results to only tests before the date passed"
          },
          "createdAfter": {
            "type": "string",
            "format": "date-time",
            "description": "Limit query results to only tests after the date passed"
          },
          "modifiedBefore": {
            "type": "string",
            "format": "date-time",
            "description": "Limit query results to only tests modified before the date passed"
          },
          "modifiedAfter": {
            "type": "string",
            "format": "date-time",
            "description": "Limit query results to only tests modified after the date passed"
          },
          "docs": {
            "type": "array",
            "description": "This is the field to query for dynamic attributes of tests. Pass in partial JSON objects and they will structurally match with query results.",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "TestQueryResult": {
        "description": "Result of a test query",
        "properties": {
          "count": {
            "type": "integer",
            "description": "count of tests returned from query"
          },
          "tests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Test"
            }
          }
        }
      }
    }
  }
}