api

Documentation

Overview

The api package defines all of our REST API endpoints.

Index

• type API
  • func New(ctx context.Context, runtime string, dc deploy.DeployConfigReader) (*API, error)
  • func (a *API) GetAccessInstructions(w http.ResponseWriter, r *http.Request, providerId string, ...)
  • func (a *API) GetGrants(w http.ResponseWriter, r *http.Request)
  • func (a *API) GetHealth(w http.ResponseWriter, r *http.Request)
  • func (a *API) GetProvider(w http.ResponseWriter, r *http.Request, providerId string)
  • func (a *API) GetProviderArgs(w http.ResponseWriter, r *http.Request, providerId string)
  • func (a *API) Handler(r chi.Router) http.Handler
  • func (a *API) ListProviderArgOptions(w http.ResponseWriter, r *http.Request, providerId string, argId string)
  • func (a *API) ListProviders(w http.ResponseWriter, r *http.Request)
  • func (a *API) PostGrants(w http.ResponseWriter, r *http.Request)
  • func (a *API) PostGrantsRevoke(w http.ResponseWriter, r *http.Request, grantId string)
  • func (a *API) RefreshAccessProviders(w http.ResponseWriter, r *http.Request)
  • func (a *API) ValidateGrant(w http.ResponseWriter, r *http.Request)
  • func (a *API) ValidateSetup(w http.ResponseWriter, r *http.Request)
• type Runtime

Types

type API

type API struct {
	DeployConfig deploy.DeployConfigReader

	// Clock is an interface over Go's built-in time library and
	// can be overriden for testing purposes.
	Clock clock.Clock
	// contains filtered or unexported fields
}

API holds all of our API endpoint handlers. We use a schema-first approach to ensure that the API meets our OpenAPI specification.

To add a new endpoint, follow the below steps:

1. Edit `openapi.yaml` in this repository.

2. Run `make generate` to update the generated handler code. The code is generated into types.gen.go, and the function signatures can be found on the ServerInterface interface.

3. You'll get a compilation error because API no longer meets the ServerInterface interface. The missing function will be your new endpoint. Implement the function on API, ensuring that the function signature matches the ServerInterface interface.

func New

func New(ctx context.Context, runtime string, dc deploy.DeployConfigReader) (*API, error)

New creates a new API, initialising the specified hosting runtime for the Access Handler.

func (*API) GetAccessInstructions

func (a *API) GetAccessInstructions(w http.ResponseWriter, r *http.Request, providerId string, params types.GetAccessInstructionsParams)

Get Access Instructions (GET /api/v1/providers/{providerId}/access-instructions)

func (*API) GetGrants

func (a *API) GetGrants(w http.ResponseWriter, r *http.Request)

List Grants (GET /api/v1/grants)

func (*API) GetHealth

func (a *API) GetHealth(w http.ResponseWriter, r *http.Request)

Healthcheck (GET /api/v1/health)

func (*API) GetProvider

func (a *API) GetProvider(w http.ResponseWriter, r *http.Request, providerId string)

func (*API) GetProviderArgs

func (a *API) GetProviderArgs(w http.ResponseWriter, r *http.Request, providerId string)

func (*API) Handler

func (a *API) Handler(r chi.Router) http.Handler

Handler returns a HTTP handler. Hander doesn't add any middleware. It is the caller's responsibility to add any middleware.

func (*API) ListProviderArgOptions

func (a *API) ListProviderArgOptions(w http.ResponseWriter, r *http.Request, providerId string, argId string)

func (*API) ListProviders

func (a *API) ListProviders(w http.ResponseWriter, r *http.Request)

func (*API) PostGrants

func (a *API) PostGrants(w http.ResponseWriter, r *http.Request)

Create Grant (POST /api/v1/grants)

func (*API) PostGrantsRevoke

func (a *API) PostGrantsRevoke(w http.ResponseWriter, r *http.Request, grantId string)

Revoke grant (POST /api/v1/grants/{grantId}/revoke)

func (*API) RefreshAccessProviders

func (a *API) RefreshAccessProviders(w http.ResponseWriter, r *http.Request)

Refresh Access Providers (POST /api/v1/providers/refresh)

func (*API) ValidateGrant

func (a *API) ValidateGrant(w http.ResponseWriter, r *http.Request)

run validation on a grant without provisioning any access

func (*API) ValidateSetup

func (a *API) ValidateSetup(w http.ResponseWriter, r *http.Request)

Validate an Access Provider's settings (POST /api/v1/setup/validate)

type Runtime

type Runtime interface {
	// Init contains any runtime-specific initialisation logic.
	Init(ctx context.Context) error

	// CreateGrant creates a grant by executing runtime-specific workflow logic, such as
	// initiating an AWS Step Functions workflow.
	CreateGrant(ctx context.Context, grant types.ValidCreateGrant) (types.Grant, error)

	// RevokeGrant revokes a grant by executing runtime-specific workflow logic, such as
	// initiating an AWS Step Functions workflow.
	// Revokes a grant and terminates the previous create grant workflow
	RevokeGrant(ctx context.Context, grantID string, revoker string) (*types.Grant, error)
}

A runtime is responsible for the actual execution of a grant and are tied to the hosting environment the Access Handler is running in.

Example runtimes are local (for testing only), and AWS Lambda with Step Functions.