apiws

README

Introduction

APIWS is a package to simplify creation of web servers with static web pages, (typically SPAs) and a REST API.

It's the erfect wrapper to your React app where the frontend is a set of static web page, and the backend is a go REST server.

Features

• Embed your web frontend into Go binary
• Add public or authenticated handlers
• Authentication includes Basic username/password, Yaml file with password hash, or OIDC

Project(s) using APIWS

• Hupload

Example

//go:embed admin-ui
var uiFS embed.FS

func NewApp() (*App, error) {
    api, err := apiws.New(uiFS, c.Values)
    if err != nil {
        return nil, err
    }

    api.WithAuthentication(basic.NewBasic("admin","secret"))

    api.AddPublicRoute("GET /status", statusHandler)

    api.AddRoute("GET /api/v1/resources", resourcesHandler)
    api.AddRoute("GET /api/v1/resources/{resource}", resourceHandler)

    api.Start()
}

Documentation

Overview

APIWS is a package to simplify creation of web servers with static web pages, (typically SPAs) and a REST API.

Index

• func NewBasic(username string, password *string) *basic.Basic
• func NewFile(filePath string) (*file.File, error)
• func NewOIDC(config oidc.OIDCConfig) (*oidc.OIDC, error)
• type APIWS
  • func New(staticUI fs.FS, templateData any) (*APIWS, error)
  • func (a *APIWS) AddPublicRoute(pattern string, handler http.Handler, arg ...*RouteOptions)
  • func (a *APIWS) AddRoute(pattern string, handler http.Handler, arg ...*RouteOptions)
  • func (a *APIWS) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *APIWS) Start()
  • func (a *APIWS) WithAuthentication(b auth.Authentication) *APIWS
  • func (a *APIWS) WithPort(port int) *APIWS
• type RouteOptions

Functions

func NewBasic

func NewBasic(username string, password *string) *basic.Basic

func NewFile

func NewFile(filePath string) (*file.File, error)

func NewOIDC

func NewOIDC(config oidc.OIDCConfig) (*oidc.OIDC, error)

Types

type APIWS

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

APIWS is the main structure for the API Web Server.

func New

func New(staticUI fs.FS, templateData any) (*APIWS, error)

New creates a new API Web Server. staticUI is the file system containing the web root directory and templateData contains data for templated values present in static web pages.

func (*APIWS) AddPublicRoute

func (a *APIWS) AddPublicRoute(pattern string, handler http.Handler, arg ...*RouteOptions)

AddRoute adds a new route to the API Web Server. The route will not be passed to authentication, handler will be called when pattern matches the request. arg is an optional RouteOptions struct

func (*APIWS) AddRoute

func (a *APIWS) AddRoute(pattern string, handler http.Handler, arg ...*RouteOptions)

AddRoute adds a new route to the API Web Server. handler will be called when pattern matches the request. arg is an optional RouteOptions struct

func (*APIWS) ServeHTTP

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

ServeHTTP serves a request passed in w and r, and can be used for integration tests.

func (*APIWS) Start

func (a *APIWS) Start()

Start starts the API Web Server.

func (*APIWS) WithAuthentication

func (a *APIWS) WithAuthentication(b auth.Authentication) *APIWS

WithAuthentication configures the authentication backend to use. Currently implemented authentication are auth.Basic, auth.File and auth.OIDC.

func (*APIWS) WithPort

func (a *APIWS) WithPort(port int) *APIWS

WithPort sets the HTTP port to listen on.

type RouteOptions

type RouteOptions struct {

	// Disable logging for this route. Useful for routes that are often called
	// as part of the normal behaviour of the application and would pollute the
	// logs.
	DisableLogging bool
	// contains filtered or unexported fields
}

RouteOptions contains optional arguments when adding routes