improve v1 api docs header legibility
GitHub has changed fonts and as a result h6s are extremely small.
This commit is contained in:
Jimmy Zelinskie
GitHub
parent
09d397eca9
commit
b45b625fc8
126
api/v1/README.md
126
api/v1/README.md
@ -23,12 +23,12 @@
|
||||
|
||||
## Error Handling
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
Every route can optionally provide an `Error` property on the response object.
|
||||
The HTTP status code of the response should indicate what type of failure occurred and how the client should reaction.
|
||||
|
||||
###### Client Retry Behavior
|
||||
#### Client Retry Behavior
|
||||
|
||||
| Code | Name | Retry Behavior |
|
||||
|------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
@ -37,7 +37,7 @@ The HTTP status code of the response should indicate what type of failure occurr
|
||||
| 422 | Unprocessable Entity | The request body is valid, but unsupported. This request should never be retried. |
|
||||
| 500 | Internal Server Error | The server encountered an error while processing the request. This request should be retried without change. |
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 400 Bad Request
|
||||
@ -53,15 +53,15 @@ Server: clair
|
||||
|
||||
## Layers
|
||||
|
||||
#### POST /layers
|
||||
### POST /layers
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The POST route for the Layers resource performs the indexing of a Layer from the provided path and displays the provided Layer with an updated `IndexByVersion` property.
|
||||
This request blocks for the entire duration of the downloading and indexing of the layer.
|
||||
The Authorization field is an optional value whose contents will fill the Authorization HTTP Header when requesting the layer via HTTP.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
POST http://localhost:6060/v1/layers HTTP/1.1
|
||||
@ -79,7 +79,7 @@ POST http://localhost:6060/v1/layers HTTP/1.1
|
||||
}
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 201 Created
|
||||
@ -100,26 +100,26 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### GET /layers/`:name`
|
||||
### GET /layers/`:name`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The GET route for the Layers resource displays a Layer and optionally all of its features and vulnerabilities.
|
||||
|
||||
###### Query Parameters
|
||||
#### Query Parameters
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|-----------------|------|----------|-------------------------------------------------------------------------------|
|
||||
| features | bool | optional | Displays the list of features indexed in this layer and all of its parents. |
|
||||
| vulnerabilities | bool | optional | Displays the list of vulnerabilities along with the features described above. |
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```
|
||||
GET http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52?features&vulnerabilities HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -153,19 +153,19 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### DELETE /layers/`:name`
|
||||
### DELETE /layers/`:name`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The DELETE route for the Layers resource removes a Layer and all of its children from the database.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
DELETE http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52 HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -175,19 +175,19 @@ Server: clair
|
||||
|
||||
## Namespaces
|
||||
|
||||
#### GET /namespaces
|
||||
### GET /namespaces
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The GET route for the Namespaces resource displays a list of namespaces currently being managed.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
GET http://localhost:6060/v1/namespaces HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -204,26 +204,26 @@ Server: clair
|
||||
|
||||
## Vulnerabilities
|
||||
|
||||
#### GET /namespaces/`:nsName`/vulnerabilities
|
||||
### GET /namespaces/`:nsName`/vulnerabilities
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The GET route for the Vulnerabilities resource displays the vulnerabilities data for a given namespace.
|
||||
|
||||
###### Query Parameters
|
||||
#### Query Parameters
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|---------|------|----------|------------------------------------------------------------|
|
||||
| limit | int | required | Limits the amount of the vunlerabilities data for a given namespace. |
|
||||
| page | int | required | Displays the specific page of the vunlerabilities data for a given namespace. |
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities?limit=2 HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -259,13 +259,13 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### POST /namespaces/`:name`/vulnerabilities
|
||||
### POST /namespaces/`:name`/vulnerabilities
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The POST route for the Vulnerabilities resource creates a new Vulnerability.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
POST http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities HTTP/1.1
|
||||
@ -296,7 +296,7 @@ POST http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities HTTP/1.1
|
||||
}
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 201 Created
|
||||
@ -329,25 +329,25 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### GET /namespaces/`:nsName`/vulnerabilities/`:vulnName`
|
||||
### GET /namespaces/`:nsName`/vulnerabilities/`:vulnName`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The GET route for the Vulnerabilities resource displays the current data for a given vulnerability and optionally the features that fix it.
|
||||
|
||||
###### Query Parameters
|
||||
#### Query Parameters
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|---------|------|----------|------------------------------------------------------------|
|
||||
| fixedIn | bool | optional | Displays the list of features that fix this vulnerability. |
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471?fixedIn HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -380,16 +380,16 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### PUT /namespaces/`:nsName`/vulnerabilities/`:vulnName`
|
||||
### PUT /namespaces/`:nsName`/vulnerabilities/`:vulnName`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The PUT route for the Vulnerabilities resource updates a given Vulnerability.
|
||||
The "FixedIn" property of the Vulnerability must be empty or missing.
|
||||
Fixes should be managed by the Fixes resource.
|
||||
If this vulnerability was inserted by a Fetcher, changes may be lost when the Fetcher updates.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471
|
||||
@ -413,7 +413,7 @@ PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471
|
||||
}
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -439,20 +439,20 @@ Server: clair
|
||||
```
|
||||
|
||||
|
||||
#### DELETE /namespaces/`:nsName`/vulnerabilities/`:vulnName`
|
||||
### DELETE /namespaces/`:nsName`/vulnerabilities/`:vulnName`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The DELETE route for the Vulnerabilities resource deletes a given Vulnerability.
|
||||
If this vulnerability was inserted by a Fetcher, it may be re-inserted when the Fetcher updates.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471 HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -461,19 +461,19 @@ Server: clair
|
||||
|
||||
## Fixes
|
||||
|
||||
#### GET /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes
|
||||
### GET /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The GET route for the Fixes resource displays the list of Features that fix the given Vulnerability.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -491,13 +491,13 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### PUT /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes/`:featureName`
|
||||
### PUT /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes/`:featureName`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The PUT route for the Fixes resource updates a Feature that is the fix for a given Vulnerability.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils HTTP/1.1
|
||||
@ -511,7 +511,7 @@ PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471
|
||||
}
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -526,19 +526,19 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### DELETE /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes/`:featureName`
|
||||
### DELETE /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes/`:featureName`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The DELETE route for the Fixes resource removes a Feature as fix for the given Vulnerability.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
DELETE http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -547,27 +547,27 @@ Server: clair
|
||||
|
||||
## Notifications
|
||||
|
||||
#### GET /notifications/`:name`
|
||||
### GET /notifications/`:name`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The GET route for the Notifications resource displays a notification that a Vulnerability has been updated.
|
||||
This route supports simultaneous pagination for both the `Old` and `New` Vulnerabilities' `LayersIntroducingVulnerability` property which can be extremely long.
|
||||
|
||||
###### Query Parameters
|
||||
#### Query Parameters
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|-------|--------|----------|---------------------------------------------------------------------------------------------------------------|
|
||||
| page | string | optional | Displays the specific page of the "LayersIntroducingVulnerability" property on New and Old vulnerabilities. |
|
||||
| limit | int | optional | Limits the amount of results in the "LayersIntroducingVulnerability" property on New and Old vulnerabilities. |
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
GET http://localhost:6060/v1/notifications/ec45ec87-bfc8-4129-a1c3-d2b82622175a?limit=2 HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
@ -618,21 +618,21 @@ Server: clair
|
||||
}
|
||||
```
|
||||
|
||||
#### DELETE /notifications/`:name`
|
||||
### DELETE /notifications/`:name`
|
||||
|
||||
###### Description
|
||||
#### Description
|
||||
|
||||
The delete route for the Notifications resource marks a Notification as read.
|
||||
If a notification is not marked as read, Clair will continue to notify the provided endpoints.
|
||||
The time at which this Notification was marked as read can be seen in the `Notified` property of the response GET route for Notification.
|
||||
|
||||
###### Example Request
|
||||
#### Example Request
|
||||
|
||||
```json
|
||||
DELETE http://localhost:6060/v1/notification/ec45ec87-bfc8-4129-a1c3-d2b82622175a HTTP/1.1
|
||||
```
|
||||
|
||||
###### Example Response
|
||||
#### Example Response
|
||||
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
Loading…
Reference in New Issue
Block a user