Documentation ¶
Index ¶
- Variables
- type API
- func (api *API) AddEndpoint(path string, handler interface{}, hooks ...MiddlewareHook)
- func (api *API) Call(method, path string, ctx *Context, input json.RawMessage) (out interface{}, err error)
- func (api *API) GetHandler() func(http.ResponseWriter, *http.Request)
- func (api *API) MatchEndpoint(method, path string) (*Endpoint, PathVars)
- type APIPath
- type Context
- type Endpoint
- type EndpointInput
- type MiddlewareHook
- type PathVars
Constants ¶
This section is empty.
Variables ¶
var ErrorBadRequest = errors.New("Bad request")
ErrorBadRequest represents an error from a malformed request.
var ErrorInternal = errors.New("Internal error")
ErrorInternal represents some unexpected internal error.
var ErrorNotFound = errors.New("Path not found")
ErrorNotFound represents a 404 error.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct {
Endpoints []*Endpoint
}
API is an object that holds all API methods and can dispatch them.
func (*API) AddEndpoint ¶
func (api *API) AddEndpoint(path string, handler interface{}, hooks ...MiddlewareHook)
AddEndpoint registers an endpoint with this API. It also allows adding middleware hooks to the endpoint.
func (*API) Call ¶
func (api *API) Call(method, path string, ctx *Context, input json.RawMessage) (out interface{}, err error)
Call sends the input to the endpoint and returns the result.
func (*API) GetHandler ¶
func (api *API) GetHandler() func(http.ResponseWriter, *http.Request)
GetHandler returns a handler function suitable for use in http.HandleFunc. For example:
http.HandleFunc("/", api.GetHandler()) log.Fatal(http.ListenAndServe(":8000", nil))
The provided handler takes care of access control headers, CORS requests, JSON marshalling, and error handling.
type APIPath ¶
An APIPath represents a specified path and method, such as GET/users/{uuid}.
func NewAPIPath ¶
NewAPIPath creates an APIPath object from a path string, in the format GET/users/{uuid}.
type Context ¶
type Context struct { // Request is the original http request. Request *http.Request // PathVars is the map of path variable names to values. PathVars PathVars Claims *auth.Claims }
Context represents data about the endpoint call, such as path variables, the calling user, and so on.
type Endpoint ¶
type Endpoint struct { // Path is the API path string that will be exposed as an API endpoint. Must // be unique. // // The format of Path is METHOD/path/{pathvar}. Any path variables in curly // brace notation will be parsed during API.Call and passed to Handler as // a Context struct value. Path string // Handler must be a function that receives any single input variable, an // input variable of type Context, neither, or both. It can return one // output variable of any time, an error, neither, or both in the order // (output, error). // // The input value for Handler, if not Context, will automatically be // unmarshalled from the input to API.Call. Handler interface{} // PreRequestHook is a middleware hook that runs before the handler. If the // hook returns an error, that error will be returned and the handler will // not be called. PreRequestHook MiddlewareHook // contains filtered or unexported fields }
An Endpoint represents an API procedure.
type EndpointInput ¶
type EndpointInput struct { Method string Path string Ctx *Context Input json.RawMessage }
EndpointInput represents the input to an endpoint call. These inputs can be modified by middleware hooks.
func AuthorizerHook ¶
func AuthorizerHook(input *EndpointInput, token *auth.TokenSigner) (*EndpointInput, error)
AuthorizerHook is a middleware hook that populates the context's Claims object with data from the request's authorization token. If there is no authorization token, or the token is invalid, it returns an error.
This hook effectively acts as a requirement that the authorization token is correct.
type MiddlewareHook ¶
type MiddlewareHook func(*EndpointInput) (*EndpointInput, error)
MiddlewareHook is a function type that is called for each request.
These hooks are functions which will be called before the endpoint handler is called, and can choose to modify the method, path, context, or input of the endpoint before it is passed along. If the hook returns an error, execution of the endpoint will halt. This is useful for things like authentication checks, which must happen before the function is triggered, and must be able to return early if a call isn't authorized.