api

README

api

api is a Go library for building RESTful API servers

Documentation

Index

• func Get(r *http.Request, key string) any
• func GetListenAddress(r *http.Request) string
• func HTTPError(code int, f any, a ...any) error
• func Handler(handler any, permFuncs ...func(*http.Request) bool) http.Handler
• func HandlerWS(handler func(*http.Request, *Conn), handlerOther any) http.Handler
• func Output(w http.ResponseWriter, output any)
• func Set(r *http.Request, key string, value any) *http.Request
• type Client
  • func NewClient(apiEndPoint string) *Client
  • func (c *Client) Delete(url string, dest any) error
  • func (c *Client) DisallowUnknownFields() *Client
  • func (c *Client) Get(url string, dest any) error
  • func (c *Client) Post(url string, data any, dest any) error
  • func (c *Client) Put(url string, data any, dest any) error
  • func (c *Client) Request(method, URL string, data any, dest any) error
  • func (c *Client) WithHeaderToken(ht string) *Client
  • func (c *Client) WithParamToken(pt string) *Client
  • func (c *Client) WithToken(tk string) *Client
  • func (c *Client) WithTokenPrefix(tp string) *Client
  • func (c *Client) WithUnixSocket(socket string) *Client
• type Conn
  • func (ws *Conn) Read(msg []byte) (n int, err error)
  • func (ws *Conn) Write(msg []byte) (n int, err error)
• type HTTPStatus
• type Server
  • func NewServer() *Server
  • func (s *Server) AddMiddleware(f func(next http.Handler) http.Handler)
  • func (s *Server) Get(key string) any
  • func (s *Server) Handle(pattern string, handler any, permFuncs ...func(*http.Request) bool)
  • func (s *Server) Serve(addrs ...string) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Set(key string, value any)

Functions

func Get

func Get(r *http.Request, key string) any

Get retrieves a value from a given key in this Request.

func GetListenAddress

func GetListenAddress(r *http.Request) string

GetListenAddress returns the address used by Serve in the execution of this Request.

func HTTPError

func HTTPError(code int, f any, a ...any) error

HTTPError returns an error with an embedded HTTP status code

func Handler

func Handler(handler any, permFuncs ...func(*http.Request) bool) http.Handler

Handler returns a http.Handler from a handler function.

handler must be a function with one of these signatures:

• http.Handler
• func (http.ResponseWriter, *http.Request)
• func [Input, Output any] (*http.Request, Input) (Output, error)
• func [Output any] (*http.Request) (Output, error)

If there are permFuncs, at least one of them must succeed.

If the error returned by the function implements HTTPStatus, it is used as the HTTP Status code to be returned.

func HandlerWS

func HandlerWS(handler func(*http.Request, *Conn), handlerOther any) http.Handler

HandlerWS returns a handler that tries to establish a Websocket connection, and calls handlerWS on success. If it does not success, and handlerOther is not nil, it uses that other handler.

func Output

func Output(w http.ResponseWriter, output any)

Output sends a JSON-encoded output.

func Set

func Set(r *http.Request, key string, value any) *http.Request

Set assigns a value to a given key for this Request.

Types

type Client

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

Client is a way to connect to 3rd party API servers.

func NewClient

func NewClient(apiEndPoint string) *Client

NewClient creates a new Client ready to use.

func (*Client) Delete

func (c *Client) Delete(url string, dest any) error

Delete makes a HTTP DELETE request to the API.

func (*Client) DisallowUnknownFields

func (c *Client) DisallowUnknownFields() *Client

DisallowUnknownFields causes the JSON decoder to return an error when the destination is a struct and the input contains object keys which do not match any non-ignored, exported fields in the destination.

func (*Client) Get

func (c *Client) Get(url string, dest any) error

Get makes a HTTP GET request to the API.

func (*Client) Post

func (c *Client) Post(url string, data any, dest any) error

Post makes a HTTP POST request to the API.

func (*Client) Put

func (c *Client) Put(url string, data any, dest any) error

Put makes a HTTP PUT request to the API.

func (*Client) Request

func (c *Client) Request(method, URL string, data any, dest any) error

Request makes a HTTP request to the API. If data is not a []byte, it will be encoding as a JSON object.

func (*Client) WithHeaderToken

func (c *Client) WithHeaderToken(ht string) *Client

WithHeaderToken specifies which Header line to use when sending a token.

func (*Client) WithParamToken

func (c *Client) WithParamToken(pt string) *Client

WithParamToken specifies which query parameter to use when sending a token.

func (*Client) WithToken

func (c *Client) WithToken(tk string) *Client

WithToken adds a token to a Client.

func (*Client) WithTokenPrefix

func (c *Client) WithTokenPrefix(tp string) *Client

WithTokenPrefix adds an optional prefix to the token in the Header line.

func (*Client) WithUnixSocket

func (c *Client) WithUnixSocket(socket string) *Client

WithUnixSocket causes the client to connect through this Unix domain socket, instead of using the network.

type Conn

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

Conn represents a Websocket connection.

func (*Conn) Read

func (ws *Conn) Read(msg []byte) (n int, err error)

Read implements the io.Reader interface: it reads data of a frame from the WebSocket connection. if msg is not large enough for the frame data, it fills the msg and next Read will read the rest of the frame data. it reads Text frame or Binary frame.

func (*Conn) Write

func (ws *Conn) Write(msg []byte) (n int, err error)

Write implements the io.Writer interface: it writes data as a frame to the WebSocket connection.

type HTTPStatus

type HTTPStatus interface {
	HTTPStatus() int
}

type Server

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

Server is an HTTP request multiplexer.

func NewServer

func NewServer() *Server

NewServer allocates and returns a new Server.

func (*Server) AddMiddleware

func (s *Server) AddMiddleware(f func(next http.Handler) http.Handler)

AddMiddleware adds a new middleware to the Server. This should only be called before the first call to ServeHTTP.

func (*Server) Get

func (s *Server) Get(key string) any

Get retrieves a value from a given key in this Server.

func (*Server) Handle

func (s *Server) Handle(pattern string, handler any, permFuncs ...func(*http.Request) bool)

Handle registers a handler for one pattern in the server.

The function to be called when the server receives a petition matching the pattern will be Handler(handler, permFuncs...)

func (*Server) Serve

func (s *Server) Serve(addrs ...string) error

Serve accepts incoming connections on the specified address(es) and handles each connection in a goroutine.

The addresses can have the form "network!addr" or just "addr", in which case the network is inferred ("unix" if the addr is a filename beginning with "/", or "tcp" if the addr is "host:port").

Serve always returns a non-nil error.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP sets the variables in the Request, runs the middleware functions, and dispatches the HTTP request to the correct handler from those registered in the server.

func (*Server) Set

func (s *Server) Set(key string, value any)

Set assigns a value to a given key for all the requests in a given server. Calls to Server.Set must not be concurrent.