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) 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) WithCORSHandler(ch cors.Handler) *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) 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) WithCORSHandler

func (a *API) WithCORSHandler(ch cors.Handler) *API

Allows you to specify a custom Cross-Origin Resource Sharing (CORS) policy handler for this API. By passing an object that implements the cors.Handler interface, you can control which resources can be accessed by cross-origin requests.

The input parameter `ch` is an implementation of the cors.Handler interface used to add CORS headers to the response. This method returns the receiver API instance to allow method chaining.

Please refer to the source code of cors.SameOrigin for more details on how to implement a CORS Handler.

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.