https://github.com/flimzy/hapi

Hypermedia API router and minimal framework for Go
https://github.com/flimzy/hapi

Last synced: about 1 month ago
JSON representation

Hypermedia API router and minimal framework for Go

• Host: GitHub
• URL: https://github.com/flimzy/hapi
• Owner: flimzy
• License: mit
• Created: 2015-07-02T02:56:23.000Z (almost 11 years ago)
• Default Branch: master
• Last Pushed: 2015-08-09T19:05:20.000Z (almost 11 years ago)
• Last Synced: 2025-03-02T05:44:24.672Z (over 1 year ago)
• Language: Go
• Size: 215 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

          
[![Build Status](https://travis-ci.org/flimzy/hapi.svg?branch=master)](https://travis-ci.org/flimzy/hapi)

# 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](https://github.com/julienschmidt/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](http://www.gorillatoolkit.org/pkg/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](https://github.com/julienschmidt/httprouter#web-frameworks-based-on-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](https://github.com/julienschmidt/httprouter#web-frameworks-based-on-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.