openapi: 3.1.0
info:
  title: APIClarity API Events API Inventory API
  description: APIClarity is an open source API security and observability tool that analyzes API traffic to reconstruct OpenAPI specifications, detect shadow and zombie APIs, identify API differences and changes, and provide API security alerts. This is the REST API exposed by an APIClarity deployment.
  version: 1.0.0
  contact:
    name: OpenClarity
    url: https://github.com/openclarity/apiclarity
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/api
  description: Local APIClarity deployment
tags:
- name: API Inventory
  description: Discovered APIs and their reconstructed specifications.
paths:
  /apiInventory:
    get:
      summary: Get API inventory
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/apiInventorySortKey'
      - $ref: '#/components/parameters/sortDir'
      - $ref: '#/components/parameters/apiNameIsFilter'
      - $ref: '#/components/parameters/apiNameIsNotFilter'
      - $ref: '#/components/parameters/apiNameStartsWithFilter'
      - $ref: '#/components/parameters/apiNameEndsWithFilter'
      - $ref: '#/components/parameters/apiNameContainsFilter'
      - $ref: '#/components/parameters/portIsFilter'
      - $ref: '#/components/parameters/portIsNotFilter'
      - $ref: '#/components/parameters/hasProvidedSpecFilter'
      - $ref: '#/components/parameters/hasReconstructedSpecFilter'
      - $ref: '#/components/parameters/apiIdFilter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - total
                properties:
                  total:
                    type: integer
                    description: Total filtered APIs count
                  items:
                    type: array
                    description: List of filtered APIs in the given page. List length must be lower or equal to pageSize
                    items:
                      $ref: '#/components/schemas/ApiInfo'
        default:
          description: Response
    post:
      summary: Create API inventory item
      tags:
      - API Inventory
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiInfoWithType'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInfo'
        default:
          description: Response
  /dashboard/apiUsage:
    get:
      summary: Get API usage
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUsages'
        default:
          description: Response
  /dashboard/apiUsage/mostUsed:
    get:
      summary: Get most used APIs
      tags:
      - API Inventory
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiCount'
        default:
          description: Response
  /dashboard/apiUsage/latestDiffs:
    get:
      summary: Get latest spec diffs
      tags:
      - API Inventory
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpecDiffTime'
        default:
          description: Response
  /apiInventory/{apiId}/specs:
    get:
      summary: Get provided and reconstructed open api specs for a specific API
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiSpecs'
        default:
          description: Response
  /apiInventory/{apiId}/specs/providedSpec:
    put:
      summary: Add or edit a spec for a specific API
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Json or Yaml representing openapi spec V2
              $ref: '#/components/schemas/rawSpec'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rawSpec'
        '400':
          description: Spec validation failure
          content:
            application/json:
              schema:
                type: string
        default:
          description: Response
    delete:
      summary: Unset a provided spec for a specific API
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/responses/Success'
        default:
          description: Response
  /apiInventory/{apiId}/specs/reconstructedSpec:
    delete:
      summary: Unset a reconstructed spec for a specific API
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/responses/Success'
        default:
          description: Response
  /apiInventory/{apiId}/reconstructed_swagger.json:
    get:
      summary: Get reconstructed API spec json file
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: spec in json format
                type: object
        default:
          description: Response
  /apiInventory/{apiId}/apiInfo:
    get:
      summary: Get api info from apiId
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInfoWithType'
        default:
          description: Response
  /apiInventory/apiId/fromHostAndPort:
    get:
      summary: Get apiId from host and port
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/host'
      - $ref: '#/components/parameters/port'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: api id
                type: integer
                format: uint32
        '404':
          description: API ID Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        default:
          description: Response
  /apiInventory/apiId/fromHostAndPortAndTraceSourceID:
    get:
      summary: Get apiId from host and port and Trace Source ID
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/host'
      - $ref: '#/components/parameters/port'
      - $ref: '#/components/parameters/traceSourceIdQuery'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: api id
                type: integer
                format: uint32
        '404':
          description: API ID Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        default:
          description: Response
  /apiInventory/{apiId}/provided_swagger.json:
    get:
      summary: Get provided API spec json file
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: spec in json format
                type: object
        default:
          description: Response
  /apiUsage/hitCount:
    get:
      summary: Get a hit count within a selected timeframe for the filtered API events
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/showNonApi'
      - $ref: '#/components/parameters/methodIsFilter'
      - $ref: '#/components/parameters/providedPathIDIsFilter'
      - $ref: '#/components/parameters/reconstructedPathIDIsFilter'
      - $ref: '#/components/parameters/pathIsFilter'
      - $ref: '#/components/parameters/pathIsNotFilter'
      - $ref: '#/components/parameters/pathStartsWithFilter'
      - $ref: '#/components/parameters/pathEndsWithFilter'
      - $ref: '#/components/parameters/pathContainsFilter'
      - $ref: '#/components/parameters/statusCodeIsFilter'
      - $ref: '#/components/parameters/statusCodeIsNotFilter'
      - $ref: '#/components/parameters/statusCodeGteFilter'
      - $ref: '#/components/parameters/statusCodeLteFilter'
      - $ref: '#/components/parameters/sourceIPIsFilter'
      - $ref: '#/components/parameters/sourceIPIsNotFilter'
      - $ref: '#/components/parameters/destinationIPIsFilter'
      - $ref: '#/components/parameters/destinationIPIsNotFilter'
      - $ref: '#/components/parameters/destinationPortIsFilter'
      - $ref: '#/components/parameters/destinationPortIsNotFilter'
      - $ref: '#/components/parameters/hasSpecDiffFilter'
      - $ref: '#/components/parameters/specDiffTypeIsFilter'
      - $ref: '#/components/parameters/specIsFilter'
      - $ref: '#/components/parameters/specIsNotFilter'
      - $ref: '#/components/parameters/specStartsWithFilter'
      - $ref: '#/components/parameters/specEndsWithFilter'
      - $ref: '#/components/parameters/specContainsFilter'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HitCount'
        default:
          description: Response
  /apiInventory/{apiId}/suggestedReview:
    get:
      summary: Get reconstructed spec for review
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/apiId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestedReview'
        default:
          description: Response
  /apiInventory/{reviewId}/approvedReview:
    post:
      summary: Apply the approved review to create the reconstructed spec
      tags:
      - API Inventory
      parameters:
      - $ref: '#/components/parameters/reviewId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Approved review
              $ref: '#/components/schemas/ApprovedReview'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/responses/Success'
        default:
          description: Response
components:
  schemas:
    SpecTag:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
        methodAndPathList:
          type: array
          items:
            $ref: '#/components/schemas/MethodAndPath'
    ApiCount:
      type: object
      properties:
        apiInfoId:
          type: integer
          description: hold the relevant api info id
          format: uint32
        apiType:
          $ref: '#/components/schemas/ApiType'
        numCalls:
          type: integer
        apiHostName:
          type: string
        apiPort:
          type: integer
    SpecInfo:
      description: An object containing info about a spec
      type: object
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/SpecTag'
    ApiUsage:
      type: object
      properties:
        numOfCalls:
          type: integer
          x-omitempty: false
        time:
          type: string
          format: date-time
    HitCount:
      type: object
      properties:
        count:
          type: integer
          format: int64
          x-omitempty: false
        time:
          type: string
          format: date-time
    ReviewPathItem:
      type: object
      properties:
        suggestedPath:
          description: Represents the parameterized path suggested by the engine
          type: string
        apiEventsPaths:
          description: Group of api event paths (original) that suggestedPath is representing
          type: array
          items:
            $ref: '#/components/schemas/ApiEventPathAndMethods'
    ApiUsages:
      type: object
      properties:
        existingApis:
          type: array
          items:
            $ref: '#/components/schemas/ApiUsage'
        newApis:
          type: array
          items:
            $ref: '#/components/schemas/ApiUsage'
        apisWithDiff:
          type: array
          items:
            $ref: '#/components/schemas/ApiUsage'
    DiffType:
      type: string
      default: NO_DIFF
      enum:
      - ZOMBIE_DIFF
      - SHADOW_DIFF
      - GENERAL_DIFF
      - NO_DIFF
    ApiResponse:
      description: An object that is return in all cases of failures.
      type: object
      properties:
        message:
          type: string
    SpecDiffTime:
      type: object
      properties:
        apiEventId:
          type: integer
          format: uint32
        time:
          type: string
          format: date-time
        apiHostName:
          type: string
        diffType:
          $ref: '#/components/schemas/DiffType'
    ApiEventPathAndMethods:
      type: object
      properties:
        path:
          type: string
        methods:
          type: array
          items:
            $ref: '#/components/schemas/HttpMethod'
    rawSpec:
      description: spec in json or yaml format
      type: object
      properties:
        rawSpec:
          type: string
          description: spec in json or yaml format
        createdAt:
          type: string
          format: date-time
    HttpMethod:
      type: string
      enum:
      - GET
      - HEAD
      - POST
      - PUT
      - DELETE
      - CONNECT
      - OPTIONS
      - TRACE
      - PATCH
    ApiInfoWithType:
      type: object
      allOf:
      - $ref: '#/components/schemas/ApiInfo'
      - properties:
          apiType:
            $ref: '#/components/schemas/ApiType'
    ApprovedReview:
      type: object
      properties:
        oasVersion:
          description: OpenAPI specification version to use when saving the approved spec
          type: string
          enum:
          - OASv2.0
          - OASv3.0
        reviewPathItems:
          type: array
          items:
            $ref: '#/components/schemas/ReviewPathItem'
    OpenApiSpecs:
      description: An object representing the provided and reconstructed API specs
      type: object
      properties:
        providedSpec:
          $ref: '#/components/schemas/SpecInfo'
        reconstructedSpec:
          $ref: '#/components/schemas/SpecInfo'
    MethodAndPath:
      type: object
      properties:
        path:
          type: string
        pathId:
          type: string
          format: uuid
        method:
          $ref: '#/components/schemas/HttpMethod'
    SuggestedReview:
      type: object
      properties:
        id:
          type: integer
          format: uint32
        reviewPathItems:
          type: array
          items:
            description: The suggested path items
            $ref: '#/components/schemas/ReviewPathItem'
    ApiInfo:
      type: object
      properties:
        id:
          type: integer
          format: uint32
        name:
          description: API name
          type: string
        port:
          type: integer
        hasReconstructedSpec:
          type: boolean
          default: false
        hasProvidedSpec:
          type: boolean
          default: false
        destinationNamespace:
          type: string
        traceSourceId:
          description: Trace Source ID which created this API. Null UUID 0 means it has been created by APIClarity (from the UI for example)
          type: string
          format: uuid
        traceSourceName:
          description: Trace source name
          type: string
        traceSourceType:
          description: Trace source type
          type: string
    ApiType:
      type: string
      enum:
      - INTERNAL
      - EXTERNAL
  parameters:
    statusCodeLteFilter:
      name: statusCode[lte]
      in: query
      required: false
      description: less than or equal
      schema:
        type: string
    specContainsFilter:
      name: spec[contains]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    specIsNotFilter:
      name: spec[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    pathEndsWithFilter:
      name: path[end]
      in: query
      required: false
      schema:
        type: string
    startTime:
      name: startTime
      in: query
      required: true
      description: Start time of the query
      schema:
        type: string
        format: date-time
    statusCodeGteFilter:
      name: statusCode[gte]
      in: query
      required: false
      description: greater than or equal
      schema:
        type: string
    pathIsFilter:
      name: path[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    reviewId:
      name: reviewId
      in: path
      required: true
      schema:
        type: integer
        format: uint32
    apiIdFilter:
      name: apiId
      in: query
      required: false
      description: api id to return
      schema:
        type: string
    traceSourceIdQuery:
      name: traceSourceId
      in: query
      required: true
      description: Trace Source ID
      schema:
        type: string
        format: uuid
    showNonApi:
      name: showNonApi
      in: query
      required: true
      schema:
        type: boolean
    pageSize:
      name: pageSize
      in: query
      required: true
      description: Maximum items to return
      schema:
        type: integer
        minimum: 1
        maximum: 50
    apiNameStartsWithFilter:
      name: name[start]
      in: query
      required: false
      schema:
        type: string
    providedPathIDIsFilter:
      name: providedPathID[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiType:
      name: type
      in: query
      required: true
      description: API type [INTERNAL or EXTERNAL]
      schema:
        type: string
        enum:
        - INTERNAL
        - EXTERNAL
    host:
      name: host
      in: query
      required: true
      description: api host name
      schema:
        type: string
    destinationIPIsFilter:
      name: destinationIP[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiInventorySortKey:
      name: sortKey
      in: query
      required: true
      description: Sort key
      schema:
        type: string
        enum:
        - name
        - port
        - hasReconstructedSpec
        - hasProvidedSpec
    page:
      name: page
      in: query
      required: true
      description: Page number of the query
      schema:
        type: integer
    pathContainsFilter:
      name: path[contains]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    sortDir:
      name: sortDir
      in: query
      required: false
      description: Sorting direction
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: ASC
    specStartsWithFilter:
      name: spec[start]
      in: query
      required: false
      schema:
        type: string
    statusCodeIsFilter:
      name: statusCode[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    pathStartsWithFilter:
      name: path[start]
      in: query
      required: false
      schema:
        type: string
    sourceIPIsFilter:
      name: sourceIP[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    specEndsWithFilter:
      name: spec[end]
      in: query
      required: false
      schema:
        type: string
    portIsFilter:
      name: port[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    destinationPortIsFilter:
      name: destinationPort[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiNameEndsWithFilter:
      name: name[end]
      in: query
      required: false
      schema:
        type: string
    specIsFilter:
      name: spec[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    reconstructedPathIDIsFilter:
      name: reconstructedPathID[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    hasProvidedSpecFilter:
      name: hasProvidedSpec[is]
      in: query
      required: false
      schema:
        type: boolean
    sourceIPIsNotFilter:
      name: sourceIP[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    port:
      name: port
      in: query
      required: true
      description: api port
      schema:
        type: string
    portIsNotFilter:
      name: port[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiNameIsFilter:
      name: name[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    specDiffTypeIsFilter:
      name: specDiffType[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
          - ZOMBIE_DIFF
          - SHADOW_DIFF
          - GENERAL_DIFF
          - NO_DIFF
    apiId:
      name: apiId
      in: path
      required: true
      schema:
        type: integer
        format: uint32
    pathIsNotFilter:
      name: path[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    endTime:
      name: endTime
      in: query
      required: true
      description: End time of the query
      schema:
        type: string
        format: date-time
    destinationIPIsNotFilter:
      name: destinationIP[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiNameIsNotFilter:
      name: name[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    destinationPortIsNotFilter:
      name: destinationPort[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    statusCodeIsNotFilter:
      name: statusCode[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiNameContainsFilter:
      name: name[contains]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    methodIsFilter:
      name: method[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
          - GET
          - HEAD
          - POST
          - PUT
          - DELETE
          - CONNECT
          - OPTIONS
          - TRACE
          - PATCH
    hasReconstructedSpecFilter:
      name: hasReconstructedSpec[is]
      in: query
      required: false
      schema:
        type: boolean
    hasSpecDiffFilter:
      name: hasSpecDiff[is]
      in: query
      required: false
      schema:
        type: boolean
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: APIClarity is typically deployed inside a Kubernetes cluster behind an ingress that enforces authentication. When exposed externally, deployments commonly require a bearer token.