Go-Json-Rest

A quick and easy way to setup a RESTful JSON API

Go-Json-Rest is a thin layer on top of net/http that helps building RESTful JSON APIs easily. It provides fast URL routing using a Trie based implementation, helpers to deal with JSON requests and responses, and middlewares for additional functionalities like CORS, Auth, Gzip ...

What's new in version 2

• Middlewares, the notion of middleware is now formally defined. They can be setup as global pre-routing Middlewares wrapping all the endpoints, or on a per endpoint basis. In fact the internal code of go-json-rest is itself implemented with Middlewares, they are just hidden behind configuration boolean flags to make these very common options even easier to use.

• A new ResponseWriter. This is now an interface, and allows Middlewares to wrap the writer. The provided writer implements, in addition of rest.ResponseWriter, http.Flusher, http.CloseNotifier, and http.ResponseWriter. A lot more Go-ish, and very similar to net/http.

• The AuthBasic and CORS Middlewares have been added. More to come in the future.

• Faster, more tasks are performed at init time, and less for each request.

• New documentation, with more examples.

• A lot of other small improvements, See the Migration guide to v2

Table of content

• Features
• Install
• Vendoring
• Examples
  • Basics
    • Hello World!
    • Countries
    • Users
  • Applications
    • GORM
    • CORS
    • Basic Auth
    • Status
    • Status Auth
  • Advanced
    • Streaming
    • SPDY
    • Google App Engine
    • Basic Auth Custom
    • CORS Custom
• External Documentation
• Options
• Migration guide from v1 to v2
• Thanks

Features

• Many examples.
• Fast and scalable URL routing. It implements the classic route description syntax using a scalable trie data structure.
• Use Middlewares in order to implement and extend the functionalities. (Logging, Gzip, CORS, Auth, ...)
• Implemented as a net/http Handler. This standard interface allows combinations with other Handlers.
• Test package to help writing tests for your API.
• Monitoring statistics inspired by Memcached.

Install

This package is "go-gettable", just do:

go get github.com/ant0ine/go-json-rest/rest

Vendoring

The recommended way of using this library in your project is to use the "vendoring" method, where this library code is copied in your repository at a specific revision. This page is a good summary of package management in Go.

Examples

All the following examples can be found in dedicated examples repository: https://github.com/ant0ine/go-json-rest-examples

Basics

First examples to try, as an introduction to go-json-rest.

Hello World!

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/helloworld/main.go

Countries

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/countries/main.go

Users

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/users/main.go

Applications

Common use cases, found in many applications.

GORM

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/gorm/main.go

CORS

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/cors/main.go

Basic Auth

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/auth-basic/main.go

Status

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/status/main.go

Status Auth

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/status-auth/main.go

Advanced

Less common use cases.

Streaming

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/streaming/main.go

SPDY

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/spdy/main.go

GAE

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/gae/gaecountries/main.go

Basic Auth Custom

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/auth-basic-custom/main.go

CORS Custom

https://raw.githubusercontent.com/ant0ine/go-json-rest-examples/master/cors-custom/main.go

External Documentation

• Online Documentation (godoc.org)

Old v1 blog posts:

• [(Blog Post) Introducing Go-Json-Rest] (http://blog.ant0ine.com/typepad/2013/04/introducing-go-json-rest.html)
• [(Blog Post) Better URL Routing ?] (http://blog.ant0ine.com/typepad/2013/02/better-url-routing-golang-1.html)

Options

Things to enable in production:

• Gzip compression (default: disabled)
• Custom Logger (default: Go default)

Things to enable in development:

• Json indentation (default: enabled)
• Relaxed ContentType (default: disabled)
• Error stack trace in the response body (default: disabled)

Migration guide from v1 to v2

Go-Json-Rest follows Semver and a few breaking changes have been introduced with the v2.

The import path has changed to github.com/ant0ine/go-json-rest/rest

This is more conform to Go style, and makes goimports work.

This:

import (
        "github.com/ant0ine/go-json-rest"
)

has to be changed to this:

import (
        "github.com/ant0ine/go-json-rest/rest"
)

rest.ResponseWriter is now an interface

This change allows the ResponseWriter to be wrapped, like the one of the net/http package. This is much more powerful, and allows the creation of Middlewares that wrap the writer. The gzip option, for instance, uses this to encode the payload (see gzip.go).

This:

func (w *rest.ResponseWriter, req *rest.Request) {
        ...
}

has to be changed to this:

func (w rest.ResponseWriter, req *rest.Request) {
        ...
}

SetRoutes now takes pointers to Route

Instead of copying Route structures everywhere, pointers are now used. This is more elegant, more efficient, and will allow more sophisticated Route manipulations in the future (like reverse route resolution).

This:

handler.SetRoutes(
		rest.Route{
		      // ...
		},
)

has to be changed to this:

handler.SetRoutes(
		&rest.Route{
		      // ...
		},
)

The notion of Middleware is now formally defined

A middleware is an object satisfying this interface:

type Middleware interface {
	MiddlewareFunc(handler HandlerFunc) HandlerFunc
}

Code using PreRoutingMiddleware will have to be adapted to provide a list of Middleware objects. See the Basic Auth example.

Flush(), CloseNotify() and Write() are not directly exposed anymore

They used to be public methods of the ResponseWriter. The implementation is still there but a type assertion of the corresponding interface is now necessary. Regarding these features, a rest.ResponseWriter now behaves exactly as the http.ResponseWriter implementation provided by net/http.

This:

writer.Flush()

has to be changed to this:

writer.(http.Flusher).Flush()

The /.status endpoint is not created automatically anymore

The route has to be manually defined. See the Status example. This is more flexible (the route is customizable), and allows combination with Middlewarres. See for instance how to protect this status endpoint with the AuthBasic middleware.

Request utility methods have changed

Overall, they provide the same features, but with two methods instead of three, better names, and without the confusing UriForWithParams.

• func (r *Request) UriBase() url.URL is now func (r *Request) BaseUrl() *url.URL, Note the pointer as the returned value.

• func (r *Request) UriForWithParams(path string, parameters map[string][]string) url.URL is now func (r *Request) UrlFor(path string, queryParams map[string][]string) *url.URL.

• func (r *Request) UriFor(path string) url.URL has be removed.

Thanks

• Franck Cuny
• Yann Kerhervé
• Ask Bjørn Hansen

Copyright (c) 2013-2014 Antoine Imbert

MIT License