hyperdrive

README

hyperdrive

An opinionated micro-framework for creating Hypermedia APIs in Go.

---

Install

go get github.com/hyperdriven/hyperdrive

OR

glide get github.com/hyperdriven/hyperdrive

Config

Configuration of core features are done via Environment Variables, in accordence with 12 factor principles.

• HYPERDRIVE_ENV: (default: development, type: string) The stage in your deployment pipeline the api is currently running in. A value of production changes behviour for some features (such as whether stack traces are logged during panic recovery). Other values, such as staging, can be used but currently have no meanin in the framework other than the one you give it in your own code.
• PORT: (default: 5000, type: int) The port the server should listen on.
• GZIP_LEVEL: (default: -1, type: int) Accepts a value between -2 and 9. Invalid values will be silently discarded and the default of -1 will be used. More info on compression levels can be found in the docs, but corresponds to zlib compression levels.
• CORS_ENABLED: (default: true, type: bool) Set this to false to disable CORS support.
• CORS_HEADERS: (default: ``, type: string) A comma-seperated list of headers to allow and expose during CORS requests. These will be appended to the default set of headers that are always allowed: Accept, Accept-Language, Content-Language, and Content-Type.
• CORS_ORIGINS: (default: *, type: string) A comma-seperated list of origins to allow during CORS requests. These will replace the default value, which is to allow all origins.
• CORS_CREDENTIALS: (default: true, type: bool) Set this to false to disable authenticated CORS requests.

Docs

• GoDoc
• Wiki
• Examples

Documentation

Overview

Package hyperdrive is an opinonated micro-framework for writing hypermedia APIs. It attempts to embrace the best of Hypermedia, especially the seperation of client and server, encapsulated in the principle of HATEOAS (HTTP as the Engine of Application State).

Hyperdrive APIs are resource-oriented, make heavy use of `http.Handler` middleware patterns, and takes advantage of HTTP verbs, headers, and other transport specific features, as much as possible. Other than that, it assumes nothing about how you store and retrieve your endpoint's hypermedia respresentations.

Index

• func GetMethods(e Endpointer) []string
• func GetMethodsList(e Endpointer) string
• func NewMethodHandler(e Endpointer) http.HandlerFunc
• type API
  • func NewAPI(name string, desc string) API
  • func (api *API) AddEndpoint(e Endpointer)
  • func (api *API) CompressionMiddleware(h http.Handler) http.Handler
  • func (api *API) CorsMiddleware(h http.Handler) http.Handler
  • func (api *API) DefaultMiddlewareChain(h http.Handler) http.Handler
  • func (api *API) LoggingMiddleware(h http.Handler) http.Handler
  • func (api *API) MethodOverrideMiddleware(h http.Handler) http.Handler
  • func (api *API) RecoveryMiddleware(h http.Handler) http.Handler
  • func (api *API) Start()
• type Config
  • func NewConfig() Config
  • func (c *Config) GetPort() string
• type DeleteHandler
• type Endpoint
  • func NewEndpoint(name string, desc string, path string) *Endpoint
  • func (e *Endpoint) GetDesc() string
  • func (e *Endpoint) GetName() string
  • func (e *Endpoint) GetPath() string
• type Endpointer
• type GetHandler
• type OptionsHandler
• type PatchHandler
• type PostHandler
• type PutHandler
• type Representation
  • func PresentEndpoint(e Endpointer) Representation
• type RootResource
  • func NewRootResource(api API) *RootResource
  • func (root *RootResource) AddEndpointer(e Endpointer)
  • func (root *RootResource) Present() Representation
  • func (root *RootResource) ServeHTTP(rw http.ResponseWriter, r *http.Request)

Functions

func GetMethods

func GetMethods(e Endpointer) []string

GetMethods returns a slice of the methods an Endpoint supports.

func GetMethodsList

func GetMethodsList(e Endpointer) string

GetMethodsList returns a list of the methods an Endpoint supports.

func NewMethodHandler

func NewMethodHandler(e Endpointer) http.HandlerFunc

NewMethodHandler sets the correct http.Handler for each method, depending on the interfaces the Enpointer supports. It returns an http.HandlerFunc, ready to be served directly, wrapped in other middleware, etc.

Types

type API

type API struct {
	Name   string
	Desc   string
	Router *mux.Router
	Server *http.Server
	Root   *RootResource
	// contains filtered or unexported fields
}

API is a logical collection of one or more endpoints, connecting requests to the response handlers using a gorlla mux Router.

func NewAPI

func NewAPI(name string, desc string) API

NewAPI creates an instance of API, with an initialized Router, Config, Server, and RootResource.

func (*API) AddEndpoint

func (api *API) AddEndpoint(e Endpointer)

AddEndpoint registers endpoints, ensuring that endpoints automatically respond with a 405 error if the endpoint does not support a particular HTTP method.

func (*API) CompressionMiddleware

func (api *API) CompressionMiddleware(h http.Handler) http.Handler

CompressionMiddleware wraps the given http.Handler and returns a gzipped response if the client requests it with the Accept-Encoding header. The compression level is set to to 1, by default. You can configure this though the GZIP_LEVEL environment variable, and set it to an integer between -2 and 9.

Following zlib, levels range from 1 (Best Speed) to 9 (Best Compression); higher levels typically run slower but compress more.

-1 is the Default Compression level, and is also used if an invalid value is configured via GZIP_LEVEL.

0 attemps no compression, and only adds the necessary DEFLATE framing.

-2 disables Lempel-Ziv match searching and only performs Huffman entropy encoding. This is useful when compressing data that has already been compressed with an LZ style algorithm, such as Snappy or LZ4.

More info can be found in the docs for the compress/flate package: https://golang.org/pkg/compress/flate/

func (*API) CorsMiddleware

func (api *API) CorsMiddleware(h http.Handler) http.Handler

CorsMiddleware allows cross-origin HTTP requests to your API. The middleware is enabled by default, and can be configured via the following environment variables:

- CORS_ENABLED (bool) - CORS_ORIGINS (string) - CORS_HEADERS (string) - CORS_CREDENTIALS (bool)

func (*API) DefaultMiddlewareChain

func (api *API) DefaultMiddlewareChain(h http.Handler) http.Handler

DefaultMiddlewareChain wraps the given http.Handler in the following chain of middleware: LoggingMiddleware, RecoveryMiddleware.

func (*API) LoggingMiddleware

func (api *API) LoggingMiddleware(h http.Handler) http.Handler

LoggingMiddleware wraps the given http.Handler and outputs requests in Apache-style Combined Log format. All logging is done to STDOUT only.

func (*API) MethodOverrideMiddleware

func (api *API) MethodOverrideMiddleware(h http.Handler) http.Handler

MethodOverrideMiddleware allows clients who can not perform native PUT, PATCH, or DELETE requests to specify the HTTP method in the X-HTTP-Method-Override header. The header name is case sensitive.

func (*API) RecoveryMiddleware

func (api *API) RecoveryMiddleware(h http.Handler) http.Handler

RecoveryMiddleware wraps the given http.Handler and recovers from panics. It wil log the stacktrace if HYPERDRIVE_ENVIRONMENT env var is not set to "production".

func (*API) Start

func (api *API) Start()

Start starts the configured http server, listening on the configured Port (default: 5000). Set the PORT environment variable to change this.

type Config

type Config struct {
	Port            int    `env:"PORT" envDefault:"5000"`
	Env             string `env:"HYPERDRIVE_ENV" envDefault:"development"`
	GzipLevel       int    `env:"GZIP_LEVEL" envDefault:"-1"`
	CorsEnabled     bool   `env:"CORS_ENABLED" envDefault:"true"`
	CorsOrigins     string `env:"CORS_ORIGINS" envDefault:"*"`
	CorsHeaders     string `env:"CORS_HEADERS" envDefault:""`
	CorsCredentials bool   `env:"CORS_CREDENTIALS" envDefault:"true"`
}

Config holds configuration values from the environment, with sane defaults (where possible). Required configuration will throw a Fatal error if they are missing.

func NewConfig

func NewConfig() Config

NewConfig returns an instance of config, with values loaded from ENV vars.

func (*Config) GetPort

func (c *Config) GetPort() string

GetPort returns the formatted value of config.Port, for use by the hyperdrive server, e.g. ":5000".

type DeleteHandler

type DeleteHandler interface {
	Delete(http.ResponseWriter, *http.Request)
}

DeleteHandler interface is satisfied if the endpoint has implemented a http.Handler method called Delete(). If this is not implemented, DELETE requests will be responded to with a `405 Method Not Allowed` error.

type Endpoint

type Endpoint struct {
	EndpointName string
	EndpointDesc string
	EndpointPath string
}

Endpoint is a basic implementation of the Endpointer interface and can be used directly if desired.

func NewEndpoint

func NewEndpoint(name string, desc string, path string) *Endpoint

NewEndpoint creates an instance of Endpoint.

func (*Endpoint) GetDesc

func (e *Endpoint) GetDesc() string

GetDesc satisfies part of the Endpointer interface and returns a string containing the description of the endpoint.

func (*Endpoint) GetName

func (e *Endpoint) GetName() string

GetName satisfies part of the Endpointer interface and returns a string containing the name of the endpoint.

func (*Endpoint) GetPath

func (e *Endpoint) GetPath() string

GetPath satisfies part of the Endpointer interface and returns a string containing the path of the endpoint, used by the Router.

This string can contain named segmets, regex, and other features as described here: http://www.gorillatoolkit.org/pkg/mux

type Endpointer

type Endpointer interface {
	GetName() string
	GetDesc() string
	GetPath() string
}

Endpointer interface provides flexibility in how endpoints are created allowing for expressiveness in how developers make use of the hyperdrive package.

type GetHandler

type GetHandler interface {
	Get(http.ResponseWriter, *http.Request)
}

GetHandler interface is satisfied if the endpoint has implemented a http.Handler method called Get(). If this is not implemented, GET requests will be responded to with a `405 Method Not Allowed` error.

type OptionsHandler

type OptionsHandler interface {
	Options(http.ResponseWriter, *http.Request)
}

OptionsHandler interface is satisfied if the endpoint has implemented a http.Handler method called Options(). If this is not implemented, OPTIONS requests will be responded to with a `200 OK` and the `Allow` header will be set with a list of all the methods your endpoint does support.

type PatchHandler

type PatchHandler interface {
	Patch(http.ResponseWriter, *http.Request)
}

PatchHandler interface is satisfied if the endpoint has implemented a http.Handler method called Patch(). If this is not implemented, PATCH requests will be responded to with a `405 Method Not Allowed` error.

type PostHandler

type PostHandler interface {
	Post(http.ResponseWriter, *http.Request)
}

PostHandler interface is satisfied if the endpoint has implemented a http.Handler method called Post(). If this is not implemented, POST requests will be responded to with a `405 Method Not Allowed` error.

type PutHandler

type PutHandler interface {
	Put(http.ResponseWriter, *http.Request)
}

PutHandler interface is satisfied if the endpoint has implemented a http.Handler method called Put(). If this is not implemented, PUT requests will be responded to with a `405 Method Not Allowed` error.

type Representation

type Representation map[string]interface{}

Representation is a data structure representing the response output. The representation is used when automatically encoding responses based on the Content Type determined by content negotation.

func PresentEndpoint

func PresentEndpoint(e Endpointer) Representation

PresentEndpoint returns a Representation to describe an Endpoint for the Discovery URL.

type RootResource

type RootResource struct {
	Name      string
	Endpoints []Endpointer
}

RootResource contains information about the API and its Endpoints, and is the hypermedia respresentation returned by the Discovery URL endpoint for API clients to learn about the API.

func NewRootResource

func NewRootResource(api API) *RootResource

NewRootResource creates an instance of RootResource, based on the given API.

func (*RootResource) AddEndpointer

func (root *RootResource) AddEndpointer(e Endpointer)

AddEndpointer adds Endpointers to the slice of Endpointers on an instance of RootResource.

func (*RootResource) Present

func (root *RootResource) Present() Representation

Present returns an Representation of the RootResource to describe the API for the Discovery URL.

func (*RootResource) ServeHTTP

func (root *RootResource) ServeHTTP(rw http.ResponseWriter, r *http.Request)

ServeHTTP satisfies the http.Handler interface and returns the hypermedia representation of the Discovery URL.