httpapi

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

• func Compose(apis ...API) http.Handler
• func ConfigureMetrics(cfg MetricsConfig)
• func IdentifyEndpoint(r *http.Request, endpoint string)
• func SkipRequestLog(r *http.Request)
• type API
  • func WithGlobalMiddleware(globalMiddleware func(http.Handler) http.Handler) API
  • func WithoutLogging() API
• type HealthCheckAPI
  • func (h HealthCheckAPI) AddTo(r *mux.Router)
• type MetricsConfig

Functions

func Compose

func Compose(apis ...API) http.Handler

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

func IdentifyEndpoint(r *http.Request, endpoint string)

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

func SkipRequestLog(r *http.Request)

SkipRequestLog indicates that this request shall not have a "REQUEST" log line written for it.

Types

type API

type API interface {
	AddTo(r *mux.Router)
}

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

func WithGlobalMiddleware(globalMiddleware func(http.Handler) http.Handler) API

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

type HealthCheckAPI struct {
	SkipRequestLog bool
	Check          func() error // optional
}

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().