hapi

README

What is HAPI?

HAPI, short for Hypermedia API, is an HTTP router/mux for creating Hypermedia APIs (aka REST) for the Go language. It is built on top of and extends httprouter.

Design goals

My primary design goal is to extend the traditional HTTP router to also handle multiple content types easily.

Most web frameworks and HTTP routers (upon which frameworks are often written) tend to focus on a single dimension of the HTTP request: The URL.

An example from gorilla mux:

func main() {
    r := mux.NewRouter()
    r.HandleFunc("/", HomeHandler)
    r.HandleFunc("/products", ProductsHandler)
    r.HandleFunc("/articles", ArticlesHandler)
    http.Handle("/", r)
}

For simple web sites, this can be enough (or nearly enough). But in recent times, many routers have started to emphasise a second essential dimension of the HTTP request: The HTTP method.

An example from httprouter:

func main() {
    // Initialize a router as usual
    router := httprouter.New()
    router.GET("/", Index)
    router.GET("/hello/:name", Hello)

This is obviously a big improvement for authors of REST APIs. But it is my opinion that this doesn't go far enough if you want to fully leverage a Hypermedia API. The missing dimension is the media type.

Whenever your httprouter ignores a dimension you care about, you end up doing your own "routing" inside of your handler function. To handle GET and POST differently with gorilla/mux, for instance, you must check the request method within your handler, then call the appropriate function yourself.

Similarly, if you have one function that produces an HTML representation of a resource, and another that produces a PDF, your own handler must determine which media type is requested (by parsing the Accept: header in the request), then doing your own internal routing yourself.

By handling this in the router, it also makes it easier to provide a 406 error in the case that the client requests a type you can't provide, even if you only provide a single media type in your API.

We have similar problems if we need to consume requests with bodies of different media types. Perhaps you want to accept input from your clients as either JSON+Collection or as XML. You have to do all that bookkeeping and piping yourself.

Thus the primary goal of HAPI is to simplify the media type dimension of Hypermedia API routing.

Compatibility

HAPI is essentially a wrapper around httprouter, and like httprouter, it provides a couple of functions to make it easy to use http.Handler, http.HandlerFunc: hapi.Handler(), and hapi.HandlerFunc() respectively.

Documentation

Overview

hapi provides a Hypermedia API (aka "true" REST) micro-framework/toolkit

Index

• type Handle
• type HypermediaAPI
  • func New() *HypermediaAPI
  • func (h *HypermediaAPI) GET(path, ctype string, handle Handle)
  • func (h *HypermediaAPI) GETAll(path string, handle Handle)
  • func (h *HypermediaAPI) Handler(method, path, ctype string, handler http.Handler)
  • func (h *HypermediaAPI) HandlerFunc(method, path, ctype string, handlerFunc http.HandlerFunc)
  • func (h *HypermediaAPI) Register(method, path, ctype string, handle Handle)
  • func (h *HypermediaAPI) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h *HypermediaAPI) TypeAndHandler(method, path, acceptHeader string) (negotiatedType string, typeHandler Handle)
• type Params
  • func (ps Params) ByName(name string) string

Types

type Handle

type Handle func(http.ResponseWriter, *http.Request, Params)

Exact copoy of Handle

type HypermediaAPI

type HypermediaAPI struct {
	Router *httprouter.Router

	// Configurable hapi.Handler which is called when the requested media
	// type (via Accept: header) cannot be served by a registered handler.
	// If it is not set, http.Error with http.StatusUnsupportedMediaType is used.
	UnsupportedMediaType Handle
	// contains filtered or unexported fields
}

func New

func New() *HypermediaAPI

func (*HypermediaAPI) GET

func (h *HypermediaAPI) GET(path, ctype string, handle Handle)

func (*HypermediaAPI) GETAll

func (h *HypermediaAPI) GETAll(path string, handle Handle)

func (*HypermediaAPI) Handler

func (h *HypermediaAPI) Handler(method, path, ctype string, handler http.Handler)

Handler() is an adapter which allows the usage of an http.Handler as a request handle

func (*HypermediaAPI) HandlerFunc

func (h *HypermediaAPI) HandlerFunc(method, path, ctype string, handlerFunc http.HandlerFunc)

HandlerFunc() is an adaptor which allows the usage of an http.HandlerFunc as a request handle

func (*HypermediaAPI) Register

func (h *HypermediaAPI) Register(method, path, ctype string, handle Handle)

Register() registers a handler method to handle a specific Method/path/content-type combination Method and path ought to be self-explanatory. The content type argument should be a space-separated list of valid content types. Wildcards are not permitted.

func (*HypermediaAPI) ServeHTTP

func (h *HypermediaAPI) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*HypermediaAPI) TypeAndHandler

func (h *HypermediaAPI) TypeAndHandler(method, path, acceptHeader string) (negotiatedType string, typeHandler Handle)

type Params

type Params httprouter.Params

func (Params) ByName

func (ps Params) ByName(name string) string