rest

README

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, and helpers to deal with JSON requests and responses. It is not a high-level REST framework that transparently maps HTTP requests to procedure calls, on the opposite, you constantly have access to the underlying net/http objects.

Features

• Implemented as a net/http Handler. This standard interface allows combinations with other Handlers.
• Fast URL routing. It implements the classic route description syntax using a fast and scalable trie data structure.
• Optional /.status endpoint for easy monitoring.
• Examples

Install

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

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

Example

package main
import (
        "github.com/ant0ine/go-json-rest"
        "net/http"
)
type User struct {
        Id   string
        Name string
}
func GetUser(w *rest.ResponseWriter, req *rest.Request) {
        user := User{
                Id:   req.PathParam("id"),
                Name: "Antoine",
        }
        w.WriteJson(&user)
}
func main() {
        handler := rest.ResourceHandler{}
        handler.SetRoutes(
                rest.Route{"GET", "/users/:id", GetUser},
        )
        http.ListenAndServe(":8080", &handler)
}

More Examples

• Countries Demo very simple GET, POST, DELETE operations
• Users Demo the mapping to object methods
• SPDY Demo SPDY using github.com/shykes/spdy-go

Documentation

• Online Documentation (godoc.org)
• [(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)
• Error stack trace in the response body (default: disabled)

The Status Endpoint

Inspired by memcached "stats", this optional feature can be enabled to help monitoring the service.

GET /.status returns something like:

{
  "Pid": 21732,
  "UpTime": "1m15.926272s",
  "UpTimeSec": 75.926272,
  "Time": "2013-03-04 08:00:27.152986 +0000 UTC",
  "TimeUnix": 1362384027,
  "StatusCodeCount": {
    "200": 53,
    "404": 11
  },
  "TotalCount": 64,
  "TotalResponseTime": "16.777ms",
  "TotalResponseTimeSec": 0.016777,
  "AverageResponseTime": "262.14us",
  "AverageResponseTimeSec": 0.00026214
}

Thanks

• Franck Cuny
• Ask Bjørn Hansen

Copyright (c) 2013 Antoine Imbert

MIT License

Documentation

Overview

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, and helpers to deal with JSON requests and responses. It is not a high-level REST framework that transparently maps HTTP requests to procedure calls, on the opposite, you constantly have access to the underlying net/http objects.

Example:

package main

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

type User struct {
        Id   string
        Name string
}

func GetUser(w *rest.ResponseWriter, req *rest.Request) {
        user := User{
                Id:   req.PathParam("id"),
                Name: "Antoine",
        }
        w.WriteJson(&user)
}

func main() {
        handler := rest.ResourceHandler{}
        handler.SetRoutes(
                rest.Route{"GET", "/users/:id", GetUser},
        )
        http.ListenAndServe(":8080", &handler)
}

Note about the URL routing: Instead of using the usual "evaluate all the routes and return the first regexp that matches" strategy, it uses a Trie data structure to perform the routing. This is more efficient, and scales better for a large number of routes. It supports the :param and *splat placeholders in the route strings.

Index

• func Error(w *Response, error string, code int)
• func NotFound(w *Response, r *Request)
• type Request
  • func (self *Request) DecodeJsonPayload(v interface{}) error
  • func (self *Request) PathParam(name string) string
  • func (self *Request) UriBase() url.URL
  • func (self *Request) UriFor(path string) url.URL
  • func (self *Request) UriForWithParams(path string, parameters map[string][]string) url.URL
• type ResourceHandler
  • func (self *ResourceHandler) ServeHTTP(origWriter http.ResponseWriter, origRequest *http.Request)
  • func (self *ResourceHandler) SetRoutes(routes ...Route) error
• type Response
  • func (self *Response) Write(b []byte) (int, error)
  • func (self *Response) WriteHeader(code int)
  • func (self *Response) WriteJson(v interface{}) error
• type Route
  • func RouteObjectMethod(httpMethod string, pathExp string, objectInstance interface{}, ...) Route

Functions

func Error

func Error(w *Response, error string, code int)

Produce an error response in JSON with the following structure, '{"Error":"My error message"}' The standard plain text net/http Error helper can still be called like this: http.Error(w, "error message", code)

func NotFound

func NotFound(w *Response, r *Request)

Produce a 404 response with the following JSON, '{"Error":"Resource not found"}' The standard plain text net/http NotFound helper can still be called like this: http.NotFound(w, r.Request)

Types

type Request

type Request struct {
	*http.Request
	// map of parameters that have been matched in the URL Path.
	PathParams map[string]string
}

Inherit from http.Request, and provide additional methods.

func (*Request) DecodeJsonPayload

func (self *Request) DecodeJsonPayload(v interface{}) error

Read the request body and decode the JSON using json.Unmarshal

func (*Request) PathParam

func (self *Request) PathParam(name string) string

Provide a convenient access to the PathParams map

func (*Request) UriBase

func (self *Request) UriBase() url.URL

Returns a URL structure for the base (scheme + host) of the application, without the trailing slash in the host

func (*Request) UriFor

func (self *Request) UriFor(path string) url.URL

Returns an URL structure from the base and an additional path.

func (*Request) UriForWithParams

func (self *Request) UriForWithParams(path string, parameters map[string][]string) url.URL

Returns an URL structure from the base, the path and the parameters.

type ResourceHandler

type ResourceHandler struct {

	// If true, and if the client accepts the Gzip encoding, the response payloads
	// will be compressed using gzip, and the corresponding response header will set.
	EnableGzip bool

	// If true, the JSON payload will be written in one line with no space.
	DisableJsonIndent bool

	// If true, the status service will be enabled. Various stats and status will
	// then be available at GET /.status in a JSON format.
	EnableStatusService bool

	// If true, when a "panic" happens, the error string and the stack trace will be
	// printed in the 500 response body.
	EnableResponseStackTrace bool

	// If true, the record that is logged for each response will be printed as JSON
	// in the log. Convenient for log parsing.
	EnableLogAsJson bool

	// Custom logger, defaults to log.New(os.Stderr, "", log.LstdFlags)
	Logger *log.Logger
	// contains filtered or unexported fields
}

Implement the http.Handler interface and act as a router for the defined Routes. The defaults are intended to be developemnt friendly, for production you may want to turn on gzip and disable the JSON indentation.

func (*ResourceHandler) ServeHTTP

func (self *ResourceHandler) ServeHTTP(origWriter http.ResponseWriter, origRequest *http.Request)

This makes ResourceHandler implement the http.Handler interface. You probably don't want to use it directly.

func (*ResourceHandler) SetRoutes

func (self *ResourceHandler) SetRoutes(routes ...Route) error

Define the Routes. The order the Routes matters, if a request matches multiple Routes, the first one will be used.

type Response

type Response struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

Inherit from an object implementing the http.ResponseWriter interface, and provide additional methods.

func (*Response) Write

func (self *Response) Write(b []byte) (int, error)

Overloading of the http.ResponseWriter method. Provide additional capabilities, like transparent gzip encoding.

func (*Response) WriteHeader

func (self *Response) WriteHeader(code int)

Overloading of the http.ResponseWriter method. Just record the status code for logging.

func (*Response) WriteJson

func (self *Response) WriteJson(v interface{}) error

Encode the object in JSON, set the content-type header, and call Write.

type Route

type Route struct {

	// Any http method. It will be used as uppercase to avoid common mistakes.
	HttpMethod string

	// A string like "/resource/:id.json".
	// Placeholders supported are:
	// :param that matches any char to the first '/' or '.'
	// *splat that matches everything to the end of the string
	// (placeholder names should be unique per PathExp)
	PathExp string

	// Code that will be executed when this route is taken.
	Func func(*Response, *Request)
}

Used with SetRoutes.

func RouteObjectMethod

func RouteObjectMethod(httpMethod string, pathExp string, objectInstance interface{}, objectMethod string) Route

Create a Route that points to an object method. It can be convenient to point to an object method instead of a function, this helper makes it easy by passing the object instance and the method name as parameters.