apiv1

Documentation

Overview

Package apiv1 provides a JSON API for interacting with clients.

This package can be imported to get an http.Handler that will enable creating, reading, updating, and deleting Clients.

The lockbox.dev/hmac package is used to authenticate requests with HMAC authentication. Authentication grants read and write access for all clients and redirect URIs in the clients system. Authentication is meant to be simple and to distinguish administrators from unauthorized users; no other roles are expected to interact with the API. The Key used to sign a request will be stored as the CreatedBy property on clients and redirect URIs. The IP the request was made from will be stored as CreatedByIP.

Index

• type APIv1
  • func (a APIv1) Server(baseURL string) http.Handler
  • func (a APIv1) VerifyRequest(r *http.Request) (string, *Response)
• type Client
• type RedirectURI
• type Response

Types

type APIv1

type APIv1 struct {
	Storer clients.Storer
	Log    *yall.Logger
	Signer hmac.Signer
}

APIv1 holds all the information that we want to be available for all the functions in the API, things like our logging, metrics, and other telemetry.

func (APIv1) Server

func (a APIv1) Server(baseURL string) http.Handler

Server returns an http.Handler that will handle all the requests for v1 of the API. The baseURL should be set to whatever prefix the muxer matches to pass requests to the Handler; consider it the root path of v1 of the API.

func (APIv1) VerifyRequest

func (a APIv1) VerifyRequest(r *http.Request) (string, *Response)

VerifyRequest calculates the HMAC signature of `r` and compares it to the passed Authorization header, while also checking the claimed SHA256 hash of the content matches the body of the request. It either returns the body of the request, or a Response indicating the error in the request. If Response is not nil, it is meant to be returned, short-circuiting the request. If Response is nil, the returned string can safely be assumed to be an authenticated request body.

type Client

type Client struct {
	ID           string    `json:"id"`
	Name         string    `json:"name"`
	Confidential bool      `json:"confidential"`
	CreatedAt    time.Time `json:"createdAt"`
	CreatedBy    string    `json:"createdBy"`
	CreatedByIP  string    `json:"createdByIP"`
	Secret       string    `json:"secret,omitempty"`
}

Client is an API-specific representation of a client.

type RedirectURI

type RedirectURI struct {
	ID          string    `json:"ID"`
	URI         string    `json:"URI"`
	IsBaseURI   bool      `json:"isBaseURI"`
	ClientID    string    `json:"clientID"`
	CreatedAt   time.Time `json:"createdAt"`
	CreatedBy   string    `json:"createdBy"`
	CreatedByIP string    `json:"createdByIP"`
}

RedirectURI is an API-specific representation of a redirect URI.

type Response

type Response struct {
	Clients      []Client           `json:"clients,omitempty"`
	RedirectURIs []RedirectURI      `json:"redirectURIs,omitempty"`
	Errors       []api.RequestError `json:"errors,omitempty"`
	Status       int                `json:"-"`
}

Response is used to encode JSON responses; it is the global response format for all API responses.