Discovered APIs and their reconstructed specifications.
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.