api

Documentation

Index

• func RawJSONBody(mode bool)
• func SetGzipLevel(level int)
• type API
  • func ListAPIs(endPoint string, nr *hap.NetRange) *API
  • func New(endPoint string) *API
  • func (a *API) AllowCORS(sites ...string) *API
  • func (a *API) EnableGZIP() *API
  • func (a *API) Endpoint() string
  • func (a *API) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *API) Spec(f *message.Printer) []hap.ApiSpec
  • func (a *API) WithCorsHeaders(heads ...string) *API
  • func (a *API) WithCorsMethods(verbs ...string) *API
  • func (a *API) WithHandlers(hs ...*handler.Handler) *API
  • func (a *API) WithRawJSONBody() *API
  • func (a *API) WithTags(tags ...tag.Tag) *API

Functions

func RawJSONBody

func RawJSONBody(mode bool)

Sets whether raw JSON body mode is globally enabled. If all APIs are supposed to allow raw JSON bodies, it is more convenient to use this function rather than the per-API version [WithRawJSONBody]. See the "Arguments" section in the HAP specification for details.

func SetGzipLevel

func SetGzipLevel(level int)

Sets the GZip compression level. The level must be between gzip.HuffmanOnly and gzip.BestCompression.

Types

type API

type API struct {
	// contains filtered or unexported fields
}

Defines an HTTP API interface

func ListAPIs

func ListAPIs(endPoint string, nr *hap.NetRange) *API

Defines an API endpoint used to output a list of API specifications (hap.ApiSpec) for documentation generation. The parameter `nr` is commonly used to restrict access to this API for internal use only:

hap.Register(api.ListAPIs("/api", hap.NetRangeFunc(cfg.Trusted)))

Where `cfg.Trusted` is a function that returns trusted CIDRs. If `nr` is nil, this endpoint is accessible only from localhost.

func New

func New(endPoint string) *API

Creates an API. The API can have multiple handlers, each of which handles a specific HTTP method, such as GET, POST, or DELETE. See [WithHandlers] for more details.

func (*API) AllowCORS

func (a *API) AllowCORS(sites ...string) *API

Enables CORS for the API. The parameter `sites` defines the allowed origins; if omitted, it defaults to all origins. To set CORS globally instead of per-API, use hap.SetGlobalCORS.

func (*API) EnableGZIP

func (a *API) EnableGZIP() *API

Enables GZip compression for the API. GZip compression is used only for GET handlers that are requested with Accept-Encoding: gzip.

func (*API) Endpoint

func (a *API) Endpoint() string

Returns the API endpoint as a string.

func (*API) ServeHTTP

func (a *API) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*API) Spec

func (a *API) Spec(f *message.Printer) []hap.ApiSpec

Spec returns the API specification as a slice of hap.ApiSpec. This method is used to generate API documentation from the code. The parameter `f` is optionally used for document localization. If it is nil, the default language (English) is used.

func (*API) WithCorsHeaders

func (a *API) WithCorsHeaders(heads ...string) *API

Sets the CORS "Access-Control-Allow-Headers" header. By default, this parameter allows Authorization and Content-Type headers.

func (*API) WithCorsMethods

func (a *API) WithCorsMethods(verbs ...string) *API

Sets the CORS methods allowed for this API. By default, GET, POST, and DELETE are allowed if not specified. If the GET method is allowed, it automatically allows the HEAD method. However, if the HEAD method is explicitly allowed without allowing GET, then GET will not be allowed.

func (*API) WithHandlers

func (a *API) WithHandlers(hs ...*handler.Handler) *API

Defines a series of handlers for an API endpoint, with each handler corresponding to an HTTP method. For example:

hap.Register(api.New("/api/end/point").WithHandlers(
    handler.GET()....,
    handler.POST()....,
    ...
))

See HAP specification for more examples.

func (*API) WithRawJSONBody

func (a *API) WithRawJSONBody() *API

Allows raw JSON bodies for HTTP requests. If this method is not called, the framework mandates that if an HTTP request's Content-Type is set to `application/json`, its body must be a JSON object representing key/value pairs. See the "Arguments" section in the HAP specification for details.

func (*API) WithTags

func (a *API) WithTags(tags ...tag.Tag) *API

Adds a Tag to each handler of the API. The Tag added here will be merged with the ones added by [Handler.WithTags]. Therefore, if the same Tag is added in both places, its value will appear twice.