Skip to content

Commit

Permalink
Used prettier to format the doc. Signed-off-by: Ritesh Udgata udgatar…
Browse files Browse the repository at this point in the history
  • Loading branch information
Ritesh-Udgata committed Oct 30, 2024
1 parent 78f4277 commit aabc735
Showing 1 changed file with 52 additions and 40 deletions.
92 changes: 52 additions & 40 deletions guac-restAPI-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,114 +5,122 @@
The GUAC REST API provides an alternative to the GUAC GraphQL API, offering simplified access to advanced queries. It is ideal for users or developers who prefer REST endpoints over GraphQL queries and need to integrate GUAC services into their own tools and scripts.

## Base URL

```
http://<host>:<port>/
```

## Endpoints

Here’s your `.yml` converted into markdown following your previous example:


### 1. /healthz

### 1. /healthz
Description: Health check to ensure the server is running correctly.
Description: Health check to ensure the server is running correctly.

Method: `GET`
Method: `GET`

Response:

```json
"Healthy"
```

### 2. /analysis/dependencies

Description: Identify the most important dependencies by frequency or score.

### 2. /analysis/dependencies
Description: Identify the most important dependencies by frequency or score.
Method: `GET`

Method: `GET`
Query Parameters:

Query Parameters:
- PaginationSpec (optional): Pagination details like page size and cursor.
- PaginationSpec (optional): Pagination details like page size and cursor.
- sort (required): Sort order of the packages. Options:
- `'frequency'`: Packages with the most dependents.
- `'frequency'`: Packages with the most dependents.
- `'scorecard'`: Packages with the lowest OpenSSF scorecard score.

Responses:
- 200 OK:
```json
[
{ "Name": "example/dependency1", "DependentCount": 100 },
{ "Name": "example/dependency2", "DependentCount": 50 }
]
```

- 200 OK:
```json
[
{ "Name": "example/dependency1", "DependentCount": 100 },
{ "Name": "example/dependency2", "DependentCount": 50 }
]
```

### 3. /v0/package/{purl}

### 3. /v0/package/{purl}
Description: Retrieve all package URLs (purls) related to the provided `purl`.
Description: Retrieve all package URLs (purls) related to the provided `purl`.

Method: `GET`
Path Parameter:
- purl (required): A URL-encoded Package URL (purl).
Path Parameter:

- purl (required): A URL-encoded Package URL (purl).

Response:

```json
{
"PaginationInfo": { "NextCursor": "abc123", "TotalCount": 2 },
"PurlList": ["pkg:foo/[email protected]", "pkg:foo/[email protected]"]
}
```

### 4. /v0/package/{purl}/vulns


### 4. /v0/package/{purl}/vulns
Description: Get vulnerabilities associated with the given `purl` and its dependencies.
Description: Get vulnerabilities associated with the given `purl` and its dependencies.

Method: `GET`
Path Parameter:
- purl (required): A URL-encoded Package URL.
Path Parameter:

- purl (required): A URL-encoded Package URL.

Query Parameter:
- includeDependencies (optional, default: `false`): Include vulnerabilities of dependencies.
Query Parameter:

- includeDependencies (optional, default: `false`): Include vulnerabilities of dependencies.

Response:

```json
[
{ "package": "pkg:foo/bar", "vulnerability": { "type": "CVE", "vulnerabilityIDs": ["CVE-2024-0001"] } }
{
"package": "pkg:foo/bar",
"vulnerability": { "type": "CVE", "vulnerabilityIDs": ["CVE-2024-0001"] }
}
]
```

### 5. /v0/artifact/{digest}/dependencies


### 5. /v0/artifact/{digest}/dependencies
Description: Retrieve dependencies associated with a specific digest.
Description: Retrieve dependencies associated with a specific digest.

Method: `GET`
Path Parameter:
- digest (required): Digest of the artifact in `<algorithm:digest>` format.
Path Parameter:

- digest (required): Digest of the artifact in `<algorithm:digest>` format.

Response:

```json
{
"PurlList": ["pkg:foo/[email protected]", "pkg:foo/[email protected]"]
}
```

### 6. Components

#### PaginationSpec Parameter

### 6. Components
Controls pagination of the results.

#### PaginationSpec Parameter
Controls pagination of the results.
```json
{
"PageSize": 10,
"Cursor": "abc123"
}
```

#### Vulnerability Schema
#### Vulnerability Schema

```json
{
"package": "pkg:foo/bar",
Expand All @@ -128,17 +136,21 @@ Controls pagination of the results.
```

## Errors handling

- 400 Bad Request: Invalid input or parameters.
- 500 Internal Server Error: Unexpected server error.
- 502 Bad Gateway: Backend connection issue.
- 404 Page Not Found

## Design Considerations

- Design of the REST API: https://github.com/guacsec/guac/issues/1544
- Infrastructure: Runs as a new binary under `cmd/rest` in the GUAC project, built using the existing Makefile setup

## Development & Contribution

The REST API is open for improvements. Developers can contribute by:

- Reporting issues via https://github.com/guacsec/guac/issues.
- Reviewing or expanding the API design through pull requests.

Expand Down

0 comments on commit aabc735

Please sign in to comment.