Documentation
¶
Overview ¶
Package httpapi contains opinionated base machinery for assembling and exposing an API consisting of HTTP endpoints.
The core of the package interface is the Compose() method, which creates a single http.Handler serving any number of HTTP APIs, each implemented as a type satisfying this package's API interface.
Compose() creates a single router that encompasses all API's endpoints, and adds a few middlewares on top that apply to all these endpoints.
Logging ¶
For each HTTP request served through this package, a plain-text log line in a format similar to nginx's "combined" format is written using the logger from package logg (by default, to stderr) using the special log level "REQUEST".
To suppress logging of specific requests, call SkipRequestLog() somewhere inside the handler.
Metrics ¶
Each HTTP request counts towards the following histogram metrics: "httpmux_first_byte_seconds", "httpmux_response_duration_seconds", "httpmux_request_size_bytes" and "httpmux_response_size_bytes".
The buckets for these histogram metrics, as well as the application name reported in the labels on these metrics, can be configured if ConfigureMetrics() is called before Compose(). Otherwise, a default choice of buckets will be applied and the application name will be read from the Component() method of package github.com/sapcc/go-api-declarations/bininfo.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Compose ¶
Compose constructs an http.Handler serving all the provided APIs. The Handler contains a few standard middlewares, as described by the package documentation.
func ConfigureMetrics ¶
func ConfigureMetrics(cfg MetricsConfig)
ConfigureMetrics sets up the metrics emitted by this package. This function must be called exactly once before the first call to Compose(), but only if the default configuration needs to be overridden.
func IdentifyEndpoint ¶
IdentifyEndpoint must be called by each endpoint handler in an API that is provided to Compose(). It identifies the endpoint for the purpose of HTTP request/response metrics.
func SkipRequestLog ¶
SkipRequestLog indicates that this request shall not have a "REQUEST" log line written for it.
Types ¶
type API ¶
API is the interface that applications can use to plug their own API endpoints into the http.Handler constructed by this package's Compose() function.
In this package, some special API instances with names like "With..." and "Without..." are available that apply to the entire http.Handler returned by Compose(), instead of just adding endpoints to it.
func WithGlobalMiddleware ¶
WithGlobalMiddleware can be given as an argument to Compose() to add a middleware to the entire http.Handler returned by Compose(). This is a similar effect to using mux.Router.Use() inside an API's AddTo() method, but explicitly declaring a global middleware like this is clearer than hiding it in one specific API implementation.
func WithoutLogging ¶
func WithoutLogging() API
WithoutLogging can be given as an argument to Compose() to disable request logging for the entire http.Handler returned by Compose().
This modifier is intended for use during unit tests.
type HealthCheckAPI ¶
HealthCheckAPI is an API with one endpoint, "GET /healthcheck", that usually just prints "ok". If the application knows how to perform a more elaborate healthcheck, it can provide a check function in the Check field. Failing the application-provided check will cause a 500 response with the resulting error message.
func (HealthCheckAPI) AddTo ¶
func (h HealthCheckAPI) AddTo(r *mux.Router)
AddTo implements the API interface.
type MetricsConfig ¶
type MetricsConfig struct {
AppName string // leave empty to use bininfo.Component()
FirstByteDurationBuckets []float64
ResponseDurationBuckets []float64
RequestBodySizeBuckets []float64
ResponseBodySizeBuckets []float64
}
MetricsConfig contains configuration options for ConfigureMetrics().
Source Files
Directories