restmachinery

Documentation

Index

• func ReadAndValidateRequestBody(w http.ResponseWriter, r *http.Request, ...) bool
• func ServeRequest(req InboundRequest)
• func ServeWebUIRequest(req InboundWebUIRequest)
• func WriteAPIResponse(w http.ResponseWriter, statusCode int, response interface{})
• type Endpoints
• type Filter
• type InboundRequest
• type InboundWebUIRequest
• type Server
  • func NewServer(endpoints []Endpoints, config *ServerConfig) Server
• type ServerConfig

Functions

func ReadAndValidateRequestBody

func ReadAndValidateRequestBody(
	w http.ResponseWriter,
	r *http.Request,
	bodySchemaLoader gojsonschema.JSONLoader,
	bodyObj interface{},
) bool

ReadAndValidateRequestBody extracts the body of the provided raw HTTP request and, if applicable, validates it against the provided gojsonschema.JSONLoader. The JSON request body is then unmarshaled into the provided object. Validation errors and all other errors are dealt with by sending an appropriate status code and response body to the client. The function returns a bool indicating success (true) or failure (false). This is a lower-level function not often used directly, but more often invoked by the ServeRequest function.

func ServeRequest

func ServeRequest(req InboundRequest)

ServeRequest handles an inbound REST API request as specified by the given InboundRequest. Handling includes, if applicable, request body validation, unmarshaling, execution of endpoint-specific logic, and response marshaling. Any errors are dealt with by sending an appropriate status code and response body to the client.

func ServeWebUIRequest

func ServeWebUIRequest(req InboundWebUIRequest)

ServeWebUIRequest handles an inbound non-API (i.e. web UI) request, presumably from a human user and not an API client, as specified by the given ServeWebUIRequest. Handling includes execution of endpoint-specific logic. Any errors are dealt with by sending an appropriate status code and response body to the client.

TODO: Figure out where this can be moved to, because it doesn't belong in the restmachinery package, although it isn't immediately clear how to cleanly separate this.

func WriteAPIResponse

func WriteAPIResponse(
	w http.ResponseWriter,
	statusCode int,
	response interface{},
)

WriteAPIResponse sends a response to the client with the specified HTTP status code and response body. The response body may be specified as raw bytes or as an object which will be marshaled to obtain response body bytes.

Types

type Endpoints

type Endpoints interface {
	// Register is invoked during Server initialization, giving endpoint
	// implementations an opportunity to register path/function mappings with
	// the provided *mux.Router.
	Register(router *mux.Router)
}

Endpoints is an interface to be implemented by all REST API endpoints.

type Filter

type Filter interface {
	// Decorate decorates one http.HandlerFunc with another.
	Decorate(http.HandlerFunc) http.HandlerFunc
}

Filter is an interface to be implemented by components that can decorate a http.HandlerFunc.

type InboundRequest

type InboundRequest struct {
	// W is the http.ResponseWriter that can be used to send a response to the
	// client.
	W http.ResponseWriter
	// R is the raw, inbound *http.Request.
	R *http.Request
	// ReqBodySchemaLoader optionally specifies a gojsonschema.JSONLoader that,
	// when applicable, can be used to validate JSON in the request body.
	ReqBodySchemaLoader gojsonschema.JSONLoader
	// ReqBodyObj optionally specifies an object into which, when applicable, the
	// JSON in the request body will be unmarshaled.
	ReqBodyObj interface{}
	// EndpointLogic implements endpoint-specific logic. Typically it will only
	// invoke a transport-agnostic function of the service layer.
	EndpointLogic func() (interface{}, error)
	// SuccessCode optionally specifies the HTTP status code for the response to
	// the client when the EndpointLogic has executed without error. If not
	// specified (i.e. left 0), 200 (OK) is assumed.
	SuccessCode int
}

InboundRequest represents an inbound REST API request.

type InboundWebUIRequest

type InboundWebUIRequest struct {
	W             http.ResponseWriter
	EndpointLogic func() (interface{}, error)
	SuccessCode   int
}

InboundWebUIRequest represents an inbound non-API (i.e. web UI) request, presumably from a human user and not an API client.

TODO: Figure out where this can be moved to, because it doesn't belong in the restmachinery package, although it isn't immediately clear how to cleanly separate this.

type Server

type Server interface {
	// Run causes the API server to start serving HTTP requests. It will block
	// until an error occurs and will return that error.
	ListenAndServe(ctx context.Context) error
}

Server is an interface for the REST API server.

func NewServer

func NewServer(endpoints []Endpoints, config *ServerConfig) Server

NewServer returns a new REST API server that serves the provided Endpoints.

type ServerConfig

type ServerConfig struct {
	Port        int
	TLSEnabled  bool
	TLSCertPath string
	TLSKeyPath  string
}

ServerConfig represents optional configuration for a REST API server.