arno/clair
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

improve v1 api docs header legibility

Browse Source 
GitHub has changed fonts and as a result h6s are extremely small.
This commit is contained in:
Jimmy Zelinskie 2016-07-11 14:35:35 -04:00 committed by GitHub
parent 09d397eca9
commit b45b625fc8
1 changed files with 63 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
api/v1/README.md
View File

@ -23,12 +23,12 @@
## Error Handling ## Error Handling
###### Description #### Description
Every route can optionally provide an `Error` property on the response object. 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. 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 | | 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. | | 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. | | 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 ```json
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
@ -53,15 +53,15 @@ Server: clair
## Layers ## 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. 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. 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. 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 ```json
POST http://localhost:6060/v1/layers HTTP/1.1 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 ```json
HTTP/1.1 201 Created 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. 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 | | Name | Type | Required | Description |
|-----------------|------|----------|-------------------------------------------------------------------------------| |-----------------|------|----------|-------------------------------------------------------------------------------|
| features | bool | optional | Displays the list of features indexed in this layer and all of its parents. | | 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. | | 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 GET http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52?features&vulnerabilities HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK 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. The DELETE route for the Layers resource removes a Layer and all of its children from the database.
###### Example Request #### Example Request
```json ```json
DELETE http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52 HTTP/1.1 DELETE http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52 HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK HTTP/1.1 200 OK
@ -175,19 +175,19 @@ Server: clair
## Namespaces ## Namespaces
#### GET /namespaces ### GET /namespaces
###### Description #### Description
The GET route for the Namespaces resource displays a list of namespaces currently being managed. The GET route for the Namespaces resource displays a list of namespaces currently being managed.
###### Example Request #### Example Request
```json ```json
GET http://localhost:6060/v1/namespaces HTTP/1.1 GET http://localhost:6060/v1/namespaces HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK HTTP/1.1 200 OK
@ -204,26 +204,26 @@ Server: clair
## Vulnerabilities ## 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. The GET route for the Vulnerabilities resource displays the vulnerabilities data for a given namespace.
###### Query Parameters #### Query Parameters
| Name | Type | Required | Description | | Name | Type | Required | Description |
|---------|------|----------|------------------------------------------------------------| |---------|------|----------|------------------------------------------------------------|
| limit | int | required | Limits the amount of the vunlerabilities data for a given namespace. | | 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. | | page | int | required | Displays the specific page of the vunlerabilities data for a given namespace. |
###### Example Request #### Example Request
```json ```json
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities?limit=2 HTTP/1.1 GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities?limit=2 HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK 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. The POST route for the Vulnerabilities resource creates a new Vulnerability.
###### Example Request #### Example Request
```json ```json
POST http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities HTTP/1.1 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 ```json
HTTP/1.1 201 Created 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. 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 | | Name | Type | Required | Description |
|---------|------|----------|------------------------------------------------------------| |---------|------|----------|------------------------------------------------------------|
| fixedIn | bool | optional | Displays the list of features that fix this vulnerability. | | fixedIn | bool | optional | Displays the list of features that fix this vulnerability. |
###### Example Request #### Example Request
```json ```json
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471?fixedIn HTTP/1.1 GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471?fixedIn HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK 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 PUT route for the Vulnerabilities resource updates a given Vulnerability.
The "FixedIn" property of the Vulnerability must be empty or missing. The "FixedIn" property of the Vulnerability must be empty or missing.
Fixes should be managed by the Fixes resource. Fixes should be managed by the Fixes resource.
If this vulnerability was inserted by a Fetcher, changes may be lost when the Fetcher updates. If this vulnerability was inserted by a Fetcher, changes may be lost when the Fetcher updates.
###### Example Request #### Example Request
```json ```json
PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471 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 ```json
HTTP/1.1 200 OK 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. 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. If this vulnerability was inserted by a Fetcher, it may be re-inserted when the Fetcher updates.
###### Example Request #### Example Request
```json ```json
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471 HTTP/1.1 GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471 HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK HTTP/1.1 200 OK
@ -461,19 +461,19 @@ Server: clair
## Fixes ## 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. The GET route for the Fixes resource displays the list of Features that fix the given Vulnerability.
###### Example Request #### Example Request
```json ```json
GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes HTTP/1.1 GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK 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. The PUT route for the Fixes resource updates a Feature that is the fix for a given Vulnerability.
###### Example Request #### Example Request
```json ```json
PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils HTTP/1.1 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 ```json
HTTP/1.1 200 OK 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. The DELETE route for the Fixes resource removes a Feature as fix for the given Vulnerability.
###### Example Request #### Example Request
```json ```json
DELETE http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils DELETE http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK HTTP/1.1 200 OK
@ -547,27 +547,27 @@ Server: clair
## Notifications ## 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. 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. 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 | | Name | Type | Required | Description |
|-------|--------|----------|---------------------------------------------------------------------------------------------------------------| |-------|--------|----------|---------------------------------------------------------------------------------------------------------------|
| page | string | optional | Displays the specific page of the "LayersIntroducingVulnerability" property on New and Old vulnerabilities. | | 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. | | limit | int | optional | Limits the amount of results in the "LayersIntroducingVulnerability" property on New and Old vulnerabilities. |
###### Example Request #### Example Request
```json ```json
GET http://localhost:6060/v1/notifications/ec45ec87-bfc8-4129-a1c3-d2b82622175a?limit=2 HTTP/1.1 GET http://localhost:6060/v1/notifications/ec45ec87-bfc8-4129-a1c3-d2b82622175a?limit=2 HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK 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. 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. 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. 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 ```json
DELETE http://localhost:6060/v1/notification/ec45ec87-bfc8-4129-a1c3-d2b82622175a HTTP/1.1 DELETE http://localhost:6060/v1/notification/ec45ec87-bfc8-4129-a1c3-d2b82622175a HTTP/1.1
``` ```
###### Example Response #### Example Response
```json ```json
HTTP/1.1 200 OK HTTP/1.1 200 OK