Serving HTTP

Mon, 01 Jan 0001 00:00:00 +0000

The httpserver package serves an http.Handler over TLS as a humus.Service. The end user’s Init sources its Settings, builds the Service with httpserver.NewService and returns it, and httpserver.Main runs it with the defaults an HTTP server behind a load balancer needs: a 5s drain and a 10s grace period. Its test package, httpservertest, runs the same App in a test, on the same defaults, with an HTTP/2 client.

The package serves an http.Handler and has no REST DSL, which is openapi/v3’s. It exports no App, runs no health Service and serves no probes: httphealth answers them, as Health probes describes. The design behind everything on this page is in Proposal: HTTP server foundation, with its revision 1 and revision 2.

Serving an API with OpenAPI

Mon, 01 Jan 0001 00:00:00 +0000

The openapi/v3 package serves an API of typed operations, and its OpenAPI document. The end user’s Init declares each operation once, on a typed path, with a typed handler and the codecs of its bodies, builds the API with openapi.NewAPI, and hands it to httpserver.NewService, which serves it over TLS as Serving HTTP describes. The same declarations serve the requests and write the document, so the two can’t disagree.

The import path names the major version of OpenAPI the package follows, and the package’s name is openapi. Two packages beside it are opt-in, and openapi uses neither: jsoncodec reads and writes JSON bodies, and problem answers errors with RFC 9457 problem details. The design behind everything on this page is in Proposal: OpenAPI endpoint DSL, as its revisions 1, 2, 3, 4 and 5 amend it.

HTTP on Humus

Serving HTTP

Serving an API with OpenAPI