APIClarity API Inventory API

openapi: 3.2.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: '#/components/schemas/SuccessResponse'
        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: '#/components/schemas/SuccessResponse'
        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: '#/components/schemas/SuccessResponse'
        default:
          description: Response
components:
  schemas:
    SpecDiffTime:
      type: object
      properties:
        apiEventId:
          type: integer
          format: uint32
        time:
          type: string
          format: date-time
        apiHostName:
          type: string
        diffType:
          $ref: '#/components/schemas/DiffType'
    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'
    ApiUsage:
      type: object
      properties:
        numOfCalls:
          type: integer
          x-omitempty: false
        time:
          type: string
          format: date-time
    ApiType:
      type: string
      enum:
      - INTERNAL
      - EXTERNAL
    SpecInfo:
      description: An object containing info about a spec
      type: object
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/SpecTag'
    HttpMethod:
      type: string
      enum:
      - GET
      - HEAD
      - POST
      - PUT
      - DELETE
      - CONNECT
      - OPTIONS
      - TRACE
      - PATCH
    SpecTag:
      type: object
      properties:
        description:
          type: string
        name:
          type: string
        methodAndPathList:
          type: array
          items:
            $ref: '#/components/schemas/MethodAndPath'
    ApiResponse:
      description: An object that is return in all cases of failures.
      type: object
      properties:
        message:
          type: string
    SuccessResponse:
      type: object
      description: 'An object that is return in cases of success that return nothing.'
      properties:
        message:
          type: string
    DiffType:
      type: string
      default: NO_DIFF
      enum:
      - ZOMBIE_DIFF
      - SHADOW_DIFF
      - GENERAL_DIFF
      - NO_DIFF
    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
    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'
    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
    ApiInfoWithType:
      type: object
      allOf:
      - $ref: '#/components/schemas/ApiInfo'
      - properties:
          apiType:
            $ref: '#/components/schemas/ApiType'
    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'
    HitCount:
      type: object
      properties:
        count:
          type: integer
          format: int64
          x-omitempty: false
        time:
          type: string
          format: date-time
    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'
    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
  parameters:
    providedPathIDIsFilter:
      name: providedPathID[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    pathIsFilter:
      name: path[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    port:
      name: port
      in: query
      required: true
      description: api port
      schema:
        type: string
    destinationIPIsFilter:
      name: destinationIP[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    pathIsNotFilter:
      name: path[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    portIsFilter:
      name: port[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    apiId:
      name: apiId
      in: path
      required: true
      schema:
        type: integer
        format: uint32
    apiNameIsNotFilter:
      name: name[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    specContainsFilter:
      name: spec[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
    apiNameEndsWithFilter:
      name: name[end]
      in: query
      required: false
      schema:
        type: string
    apiNameStartsWithFilter:
      name: name[start]
      in: query
      required: false
      schema:
        type: string
    pathContainsFilter:
      name: path[contains]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    specStartsWithFilter:
      name: spec[start]
      in: query
      required: false
      schema:
        type: string
    apiInventorySortKey:
      name: sortKey
      in: query
      required: true
      description: Sort key
      schema:
        type: string
        enum:
        - name
        - port
        - hasReconstructedSpec
        - hasProvidedSpec
    statusCodeGteFilter:
      name: statusCode[gte]
      in: query
      required: false
      description: greater than or equal
      schema:
        type: string
    reviewId:
      name: reviewId
      in: path
      required: true
      schema:
        type: integer
        format: uint32
    statusCodeIsFilter:
      name: statusCode[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    sourceIPIsNotFilter:
      name: sourceIP[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    specEndsWithFilter:
      name: spec[end]
      in: query
      required: false
      schema:
        type: string
    specIsFilter:
      name: spec[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    hasReconstructedSpecFilter:
      name: hasReconstructedSpec[is]
      in: query
      required: false
      schema:
        type: boolean
    portIsNotFilter:
      name: port[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    pathEndsWithFilter:
      name: path[end]
      in: query
      required: false
      schema:
        type: string
    statusCodeIsNotFilter:
      name: statusCode[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    statusCodeLteFilter:
      name: statusCode[lte]
      in: query
      required: false
      description: less than or equal
      schema:
        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
    destinationIPIsNotFilter:
      name: destinationIP[isNot]
      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
    host:
      name: host
      in: query
      required: true
      description: api host name
      schema:
        type: string
    apiType:
      name: type
      in: query
      required: true
      description: API type [INTERNAL or EXTERNAL]
      schema:
        type: string
        enum:
        - INTERNAL
        - EXTERNAL
    showNonApi:
      name: showNonApi
      in: query
      required: true
      schema:
        type: boolean
    startTime:
      name: startTime
      in: query
      required: true
      description: Start time of the query
      schema:
        type: string
        format: date-time
    page:
      name: page
      in: query
      required: true
      description: Page number of the query
      schema:
        type: integer
    reconstructedPathIDIsFilter:
      name: reconstructedPathID[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    hasSpecDiffFilter:
      name: hasSpecDiff[is]
      in: query
      required: false
      schema:
        type: boolean
    apiNameContainsFilter:
      name: name[contains]
      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
    pageSize:
      name: pageSize
      in: query
      required: true
      description: Maximum items to return
      schema:
        type: integer
        minimum: 1
        maximum: 50
    specIsNotFilter:
      name: spec[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    sourceIPIsFilter:
      name: sourceIP[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    destinationPortIsNotFilter:
      name: destinationPort[isNot]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    pathStartsWithFilter:
      name: path[start]
      in: query
      required: false
      schema:
        type: string
    hasProvidedSpecFilter:
      name: hasProvidedSpec[is]
      in: query
      required: false
      schema:
        type: boolean
    apiIdFilter:
      name: apiId
      in: query
      required: false
      description: api id to return
      schema:
        type: string
    destinationPortIsFilter:
      name: destinationPort[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
    traceSourceIdQuery:
      name: traceSourceId
      in: query
      required: true
      description: Trace Source ID
      schema:
        type: string
        format: uuid
    apiNameIsFilter:
      name: name[is]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string