Skip to content

Update OpenAPI docs #227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update OpenAPI docs #227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 168 additions & 5 deletions docs/reference/api/openapi-v1.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,29 @@ info:
The total number of items in the collection across all pages is
returned in the `X-Total-Count` response header.

### Bounded total counts

An exact `X-Total-Count` gets more expensive as a collection grows, and on large
collections it can time out. Some endpoints therefore accept an optional `totalCount`
query parameter that caps the cost of counting:

| `totalCount` | Description |
|--------------|--------------------------------------------------------------------|
| `EXACT` | Count every matching item. The default. Can time out. |
| `BOUNDED` | Stop counting at a server-side cap. May return only a lower bound. |

Any other value is rejected with `400`. Each endpoint documents how it computes the
bounded count, on its `totalCount` parameter.

Endpoints that accept `totalCount` also return an `X-Total-Count-Type` header saying
how to read `X-Total-Count`. They return it on every collection response, including
ones that did not opt in.

| `X-Total-Count-Type` | Meaning |
|----------------------|----------------------------------------------------------------------|
| `EXACT` | `X-Total-Count` is the true total. |
| `AT_LEAST` | `X-Total-Count` is only a lower bound. The true total may be higher. |

## HTTP Methods

| Method | Semantics |
Expand All @@ -86,6 +109,15 @@ info:

Delete (`DELETE`) operations typically return `204 No Content`.

## Timeouts

A request that takes too long to complete is aborted and answered
with `504 Gateway Timeout` and a problem details body. Any operation
can time out, so operations do not document it individually.

Requesting a bounded total count can avoid the timeout where the
operation supports it, because counting is often the expensive part.

## Deprecations

Operations may be removed or replaced over time. When a response
Expand Down Expand Up @@ -2028,6 +2060,21 @@ paths:
name: isKev
schema:
type: boolean
- description: "The counting mode for `X-Total-Count`. With `BOUNDED`, the count\
\ stops at a fixed server-side cap. `X-Total-Count` is then exact when the\
\ count finishes within the cap, or when the requested page ends the result\
\ set. Otherwise it is a lower bound, never below the end of the requested\
\ page. `X-Total-Count-Type` says which case applies. See the Pagination\
\ section of the API description."
in: query
name: totalCount
schema:
type: string
default: EXACT
description: The counting mode for the `X-Total-Count` response header.
enum:
- EXACT
- BOUNDED
responses:
"200":
content:
Expand All @@ -2039,10 +2086,19 @@ paths:
description: A list of all findings
headers:
X-Total-Count:
description: The total number of findings
description: "The number of findings, exact or a lower bound. See `X-Total-Count-Type`."
schema:
format: integer
style: simple
X-Total-Count-Type:
$ref: "#/components/headers/TotalCountType"
style: simple
"400":
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
description: Invalid query parameter
"401":
description: Unauthorized
security:
Expand Down Expand Up @@ -2189,6 +2245,21 @@ paths:
name: isKev
schema:
type: boolean
- description: "The counting mode for `X-Total-Count`. With `BOUNDED`, the count\
\ is skipped and `X-Total-Count` reports what the requested page itself\
\ proves. `X-Total-Count-Type` is then `EXACT` when the page ends the result\
\ set, and `AT_LEAST` otherwise. A page past the end reports `AT_LEAST`\
\ with a count of 0, which means the total is unknown. See the Pagination\
\ section of the API description."
in: query
name: totalCount
schema:
type: string
default: EXACT
description: The counting mode for the `X-Total-Count` response header.
enum:
- EXACT
- BOUNDED
responses:
"200":
content:
Expand All @@ -2200,10 +2271,19 @@ paths:
description: A list of all findings grouped by vulnerability
headers:
X-Total-Count:
description: The total number of findings
description: "The number of findings, exact or a lower bound. See `X-Total-Count-Type`."
schema:
format: integer
style: simple
X-Total-Count-Type:
$ref: "#/components/headers/TotalCountType"
style: simple
"400":
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
description: Invalid query parameter
"401":
description: Unauthorized
security:
Expand Down Expand Up @@ -2315,6 +2395,21 @@ paths:
name: isKev
schema:
type: boolean
- description: "The counting mode for `X-Total-Count`. With `BOUNDED`, the count\
\ stops at a fixed server-side cap. `X-Total-Count` is then exact when the\
\ count finishes within the cap, or when the requested page ends the result\
\ set. Otherwise it is a lower bound, never below the end of the requested\
\ page. `X-Total-Count-Type` says which case applies. See the Pagination\
\ section of the API description."
in: query
name: totalCount
schema:
type: string
default: EXACT
description: The counting mode for the `X-Total-Count` response header.
enum:
- EXACT
- BOUNDED
responses:
"200":
content:
Expand All @@ -2327,13 +2422,22 @@ paths:
schema:
type: string
description: "A list of all findings for a specific project, or a SARIF\
\ file"
\ file. SARIF responses carry no count headers."
headers:
X-Total-Count:
description: The total number of findings
description: "The number of findings, exact or a lower bound. See `X-Total-Count-Type`."
schema:
format: integer
style: simple
X-Total-Count-Type:
$ref: "#/components/headers/TotalCountType"
style: simple
"400":
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetails"
description: Invalid query parameter
"401":
description: Unauthorized
"403":
Expand Down Expand Up @@ -7638,8 +7742,52 @@ paths:
- team
/v1/team/visible:
get:
description: <p></p>
description: <p>Optional query parameter <code>searchText</code>. The search
is case insensitive and matches team names.</p>
operationId: availableTeams
parameters:
- description: Optional case-insensitive substring match on team name.
in: query
name: searchText
schema:
type: string
- description: The page to return. To be used in conjunction with <code>pageSize</code>.
in: query
name: pageNumber
schema:
type: string
default: "1"
- description: Number of elements to return per page. To be used in conjunction
with <code>pageNumber</code>.
in: query
name: pageSize
schema:
type: string
default: "100"
- description: Offset to start returning elements from. To be used in conjunction
with <code>limit</code>.
in: query
name: offset
schema:
type: string
- description: Number of elements to return per page. To be used in conjunction
with <code>offset</code>.
in: query
name: limit
schema:
type: string
- description: Name of the resource field to sort on.
in: query
name: sortName
schema:
type: string
- description: Ordering of items when sorting with <code>sortName</code>.
in: query
name: sortOrder
schema:
type: string
enum:
- "asc, desc"
responses:
"200":
content:
Expand All @@ -7649,6 +7797,12 @@ paths:
items:
$ref: "#/components/schemas/VisibleTeams"
description: The Visible Teams
headers:
X-Total-Count:
description: The total number of visible teams
schema:
format: integer
style: simple
"401":
description: Unauthorized
security:
Expand Down Expand Up @@ -9485,6 +9639,15 @@ paths:
tags:
- version
components:
headers:
TotalCountType:
description: Whether `X-Total-Count` is exact (`EXACT`) or a lower bound (`AT_LEAST`).
`AT_LEAST` with a count of 0 means the total is unknown.
schema:
type: string
enum:
- EXACT
- AT_LEAST
schemas:
About:
type: object
Expand Down
14 changes: 13 additions & 1 deletion docs/reference/api/openapi-v2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,10 @@ info:
}
```

A request that takes too long to complete is aborted and rejected
with `504 Gateway Timeout`. Any operation can time out, so operations
do not document it individually.

## Authentication

Two credential types are accepted:
Expand Down Expand Up @@ -2832,12 +2836,16 @@ components:
list-extensions-response-item:
required:
- configurable
- display_name
- name
- testable
type: object
properties:
name:
type: string
display_name:
type: string
description: Human-readable name of the extension.
configurable:
type: boolean
description: Whether the extension supports runtime configuration.
Expand Down Expand Up @@ -3102,6 +3110,7 @@ components:
kev-assertion:
required:
- asserter
- asserter_display_name
- created_at
- updated_at
- vuln_id
Expand All @@ -3111,7 +3120,10 @@ components:
asserter:
type: string
description: "The entity that asserted the vulnerability is known to be\
\ exploited (e.g. `CISA`, `ENISA`)."
\ exploited (e.g. `cisa`, `enisa`)."
asserter_display_name:
type: string
description: Human-readable name of the asserting entity (e.g. `CISA KEV`).
vuln_source:
type: string
description: Source of the asserted vulnerability identifier (e.g. `NVD`).
Expand Down