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

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

• type API
  • func NewAPI() API
  • func (api *API) AddEndpoint(e Endpointer)
  • func (api *API) LoggingMiddleware(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

Types

type API

type API struct {
	Router *mux.Router
	Server *http.Server
	// 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() API

NewAPI creates an instance of an API with an initialized Router.

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) 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) 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_ENVIRONMENT" envDefault:"development"`
}

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 how developers make use of this 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.