Skip to content

Commit

Permalink
Implemented the REST API
Browse files Browse the repository at this point in the history
* Fixes guacsec#1326
* Implemented the REST API for Known
*
  • Loading branch information
nathannaveen committed Oct 31, 2023
1 parent 25250e2 commit 6fdf7fa
Show file tree
Hide file tree
Showing 10 changed files with 1,377 additions and 0 deletions.
22 changes: 22 additions & 0 deletions cmd/rest/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# REST API Documentation

## Implementation:

* Using gin-gonic gin framework for building REST API

## Available HTTP Methods:

* **GET** pURL - Fetches a known item using a given pURL. The pURL is a mandatory parameter.
* **Success Response**:
* If the pURL is valid and the known item is found, the server responds with HTTP status code `200` and includes the known item in the response body.
* **Error Responses**:
* If the pURL is invalid, the server responds with HTTP status code `400` (Bad Request).
* If the known item is not found for the provided pURL, the server responds with HTTP status code `404` (Not Found).
* For any other server errors, the server responds with HTTP status code `500` (Internal Server Error).

## Endpoints:

- `/known/package/*hash`
- `/known/source/*vcs`
- `/known/artifact/*artifact`
- `/vuln/*purl`
54 changes: 54 additions & 0 deletions cmd/rest/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Experimental REST Feature Design Document

***This is a work-in-progress document.***
## Introduction

The Experimental REST service is a new addition to the GUAC project. It aims to provide a RESTful API interface for querying data from GUAC. This interface complements the existing GraphQL interface, providing an enhanced way for users to query the GUAC data.

## Goals

1. **Provide a RESTful API interface**: The primary goal of this feature is to provide a RESTful API interface that provides a simplified response to complex questions.

2. **Support advanced queries**: The REST API contains advanced queries. These queries require complex client-side filtering, type checking, iteration, or path finding using the existing GraphQL interface. This interface contains all that logic in simple REST API.

3. **Ensure compatibility with existing systems**: The REST API should adhere to REST conventions and best practices so that it is intuitive to consumers and is compatible with existing systems and tools that use RESTful APIs.

## Proposed Design

The REST API will be implemented using the Gin web framework in Go. The API will provide endpoints for querying packages, dependencies, and other related data.

### Why Gin?

Gin is a high-performance web framework for Go that provides robust features for building web applications. It is efficient, lean, and fully compatible with the `net/http` library, making it an excellent choice for implementing a REST API. Furthermore, Gin has a large and active community, ensuring it is well-maintained and up-to-date with the latest best practices in web development.

### Why not the standard HTTP router?

While the standard HTTP router in Go is powerful and flexible, it lacks some of the features and conveniences that Gin provides. For instance, Gin provides middleware support, better error handling, and routing capabilities that are more advanced than the standard HTTP router. Gin is known for its fast routing and request handling. It uses a radix tree for routing, which can sometimes be faster than the standard library's regular expression-based routing.

### Endpoints

The following endpoints will be provided:

- `/known/package/*hash`: This endpoint will retrieve information about a known package based on its hash. The response will include details about the package and its neighbors.
- `/known/source/*vcs`: This endpoint will retrieve information about a known source based on its VCS. The response will include details about the source and its neighbors.
- `/known/artifact/*artifact`: This endpoint will retrieve information about a known artifact based on the artifact provided. The response will include details about the artifact and its neighbors.
- `/vuln/*purl`: This endpoint will retrieve information about a vulnerability based on its purl. The response will include details about the vulnerability and its neighbors.

### Data Models

The data returned by the REST API will be structured according to the following models:

- `Neighbors`: This model will represent the neighbors of a package. It will include fields for the neighbor's hash, scorecards, occurrences, and other relevant details.

### Error Handling

The REST API will return appropriate HTTP status codes in case of errors.

### Dependencies

- `graphql`: This library will interact with the GUAC database. It will allow the API to perform advanced queries and retrieve detailed information about packages and their dependencies.

## References

- Experimental-REST issue on GitHub: [https://github.com/guacsec/guac/issues/1326](https://github.com/guacsec/guac/issues/1326)
- Gin web framework: [https://github.com/gin-gonic/gin](https://github.com/gin-gonic/gin)
138 changes: 138 additions & 0 deletions cmd/rest/guac_rest_api_spec.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
openapi: 3.0.0
info:
title: GUAC REST API
version: 0.1.0
paths:
/known/package/{hash}:
get:
summary: Returns known item for a given pURL
parameters:
- name: hash
in: path
required: true
schema:
type: string
responses:
'200':
description: Known item found
content:
application/json:
schema:
$ref: '#/components/schemas/Neighbors'
'400':
description: Known item not found
'500':
description: Internal Server Error
/known/source/{vcs}:
get:
summary: Returns known item for a given VCS
parameters:
- name: vcs
in: path
required: true
schema:
type: string
responses:
'200':
description: Known item found
content:
application/json:
schema:
$ref: '#/components/schemas/Neighbors'
'400':
description: Known item not found
'500':
description: Internal Server Error
components:
schemas:
Neighbors:
type: object
properties:
HashEquals:
type: array
items:
$ref: '#/components/schemas/HashEqual'
Scorecards:
type: array
items:
$ref: '#/components/schemas/Scorecard'
Occurrences:
type: array
items:
$ref: '#/components/schemas/Occurrence'
HasSrcAt:
type: array
items:
$ref: '#/components/schemas/HasSourceAt'
HasSBOMs:
type: array
items:
$ref: '#/components/schemas/HasSBOM'
HasSLSAs:
type: array
items:
$ref: '#/components/schemas/HasSLSA'
CertifyVulns:
type: array
items:
$ref: '#/components/schemas/CertifyVuln'
VexLinks:
type: array
items:
$ref: '#/components/schemas/VEXStatement'
BadLinks:
type: array
items:
$ref: '#/components/schemas/BadLink'
GoodLinks:
type: array
items:
$ref: '#/components/schemas/GoodLink'
PkgEquals:
type: array
items:
$ref: '#/components/schemas/PkgEqual'
HashEqual:
type: object
properties:
// properties of HashEqual
Scorecard:
type: object
properties:
// properties of Scorecard
Occurrence:
type: object
properties:
// properties of Occurrence
HasSourceAt:
type: object
properties:
// properties of HasSourceAt
HasSBOM:
type: object
properties:
// properties of HasSBOM
HasSLSA:
type: object
properties:
// properties of HasSLSA
CertifyVuln:
type: object
properties:
// properties of CertifyVuln
VEXStatement:
type: object
properties:
// properties of VEXStatement
BadLink:
type: object
properties:
// properties of BadLink
GoodLink:
type: object
properties:
// properties of GoodLink
PkgEqual:
type: object
properties:
// properties of PkgEqual
Loading

0 comments on commit 6fdf7fa

Please sign in to comment.