go-json-rest: github.com/ant0ine/go-json-rest/rest Index | Files | Directories

package rest

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

A quick and easy way to setup a RESTful JSON API

http://ant0ine.github.io/go-json-rest/

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

Example:

package main

import (
        "github.com/ant0ine/go-json-rest/rest"
        "log"
        "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() {
        api := rest.NewApi()
        api.Use(rest.DefaultDevStack...)
        router, err := rest.MakeRouter(
                rest.Get("/users/:id", GetUser),
        )
        if err != nil {
                log.Fatal(err)
        }
        api.SetApp(router)
        log.Fatal(http.ListenAndServe(":8080", api.MakeHandler()))
}

Index

Package Files

access_log_apache.go access_log_json.go api.go auth_basic.go content_type_checker.go cors.go doc.go gzip.go if.go json_indent.go jsonp.go middleware.go powered_by.go recorder.go recover.go request.go response.go route.go router.go status.go timer.go

Constants

const (
    // CommonLogFormat is the Common Log Format (CLF).
    CommonLogFormat = "%h %l %u %t \"%r\" %s %b"

    // CombinedLogFormat is the NCSA extended/combined log format.
    CombinedLogFormat = "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""

    // DefaultLogFormat is the default format, colored output and response time, convenient for development.
    DefaultLogFormat = "%t %S\033[0m \033[36;1m%Dμs\033[0m \"%r\" \033[1;30m%u \"%{User-Agent}i\"\033[0m"
)

Variables

var DefaultCommonStack = []Middleware{
    &TimerMiddleware{},
    &RecorderMiddleware{},
    &PoweredByMiddleware{},
    &RecoverMiddleware{},
}

Defines a stack of middlewares that should be common to most of the middleware stacks.

var DefaultDevStack = []Middleware{
    &AccessLogApacheMiddleware{},
    &TimerMiddleware{},
    &RecorderMiddleware{},
    &PoweredByMiddleware{},
    &RecoverMiddleware{
        EnableResponseStackTrace: true,
    },
    &JsonIndentMiddleware{},
    &ContentTypeCheckerMiddleware{},
}

Defines a stack of middlewares convenient for development. Among other things: console friendly logging, JSON indentation, error stack strace in the response.

var DefaultProdStack = []Middleware{
    &AccessLogApacheMiddleware{
        Format: CombinedLogFormat,
    },
    &TimerMiddleware{},
    &RecorderMiddleware{},
    &PoweredByMiddleware{},
    &RecoverMiddleware{},
    &GzipMiddleware{},
    &ContentTypeCheckerMiddleware{},
}

Defines a stack of middlewares convenient for production. Among other things: Apache CombinedLogFormat logging, gzip compression.

var (
    // ErrJsonPayloadEmpty is returned when the JSON payload is empty.
    ErrJsonPayloadEmpty = errors.New("JSON payload is empty")
)
var ErrorFieldName = "Error"

This allows to customize the field name used in the error response payload. It defaults to "Error" for compatibility reason, but can be changed before starting the server. eg: rest.ErrorFieldName = "errorMessage"

func Error Uses

func Error(w ResponseWriter, error string, code int)

Error produces 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 Uses

func NotFound(w ResponseWriter, r *Request)

NotFound produces 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)

type AccessLogApacheMiddleware Uses

type AccessLogApacheMiddleware struct {

    // Logger points to the logger object used by this middleware, it defaults to
    // log.New(os.Stderr, "", 0).
    Logger *log.Logger

    // Format defines the format of the access log record. See AccessLogFormat for the details.
    // It defaults to DefaultLogFormat.
    Format AccessLogFormat
    // contains filtered or unexported fields
}

AccessLogApacheMiddleware produces the access log following a format inspired by Apache mod_log_config. It depends on TimerMiddleware and RecorderMiddleware that should be in the wrapped middlewares. It also uses request.Env["REMOTE_USER"].(string) set by the auth middlewares.

func (*AccessLogApacheMiddleware) MiddlewareFunc Uses

func (mw *AccessLogApacheMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes AccessLogApacheMiddleware implement the Middleware interface.

type AccessLogFormat Uses

type AccessLogFormat string

AccessLogFormat defines the format of the access log record. This implementation is a subset of Apache mod_log_config. (See http://httpd.apache.org/docs/2.0/mod/mod_log_config.html)

%b content length in bytes, - if 0
%B content length in bytes
%D response elapsed time in microseconds
%h remote address
%H server protocol
%l identd logname, not supported, -
%m http method
%P process id
%q query string
%r first line of the request
%s status code
%S status code preceeded by a terminal color
%t time of the request
%T response elapsed time in seconds, 3 decimals
%u remote user, - if missing
%{User-Agent}i user agent, - if missing
%{Referer}i referer, - is missing

Some predefined formats are provided as contants.

type AccessLogJsonMiddleware Uses

type AccessLogJsonMiddleware struct {

    // Logger points to the logger object used by this middleware, it defaults to
    // log.New(os.Stderr, "", 0).
    Logger *log.Logger
}

AccessLogJsonMiddleware produces the access log with records written as JSON. This middleware depends on TimerMiddleware and RecorderMiddleware that must be in the wrapped middlewares. It also uses request.Env["REMOTE_USER"].(string) set by the auth middlewares.

func (*AccessLogJsonMiddleware) MiddlewareFunc Uses

func (mw *AccessLogJsonMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes AccessLogJsonMiddleware implement the Middleware interface.

type AccessLogJsonRecord Uses

type AccessLogJsonRecord struct {
    Timestamp    *time.Time
    StatusCode   int
    ResponseTime *time.Duration
    HttpMethod   string
    RequestURI   string
    RemoteUser   string
    UserAgent    string
}

AccessLogJsonRecord is the data structure used by AccessLogJsonMiddleware to create the JSON records. (Public for documentation only, no public method uses it)

type Api Uses

type Api struct {
    // contains filtered or unexported fields
}

Api defines a stack of Middlewares and an App.

func NewApi Uses

func NewApi() *Api

NewApi makes a new Api object. The Middleware stack is empty, and the App is nil.

func (*Api) MakeHandler Uses

func (api *Api) MakeHandler() http.Handler

MakeHandler wraps all the Middlewares of the stack and the App together, and returns an http.Handler ready to be used. If the Middleware stack is empty the App is used directly. If the App is nil, a HandlerFunc that does nothing is used instead.

func (*Api) SetApp Uses

func (api *Api) SetApp(app App)

SetApp sets the App in the Api object.

func (*Api) Use Uses

func (api *Api) Use(middlewares ...Middleware)

Use pushes one or multiple middlewares to the stack for middlewares maintained in the Api object.

type App Uses

type App interface {
    AppFunc() HandlerFunc
}

App defines the interface that an object should implement to be used as an app in this framework stack. The App is the top element of the stack, the other elements being middlewares.

func MakeRouter Uses

func MakeRouter(routes ...*Route) (App, error)

MakeRouter returns the router app. Given a set of Routes, it dispatches the request to the HandlerFunc of the first route that matches. The order of the Routes matters.

type AppSimple Uses

type AppSimple HandlerFunc

AppSimple is an adapter type that makes it easy to write an App with a simple function. eg: rest.NewApi(rest.AppSimple(func(w rest.ResponseWriter, r *rest.Request) { ... }))

func (AppSimple) AppFunc Uses

func (as AppSimple) AppFunc() HandlerFunc

AppFunc makes AppSimple implement the App interface.

type AuthBasicMiddleware Uses

type AuthBasicMiddleware struct {

    // Realm name to display to the user. Required.
    Realm string

    // Callback function that should perform the authentication of the user based on userId and
    // password. Must return true on success, false on failure. Required.
    Authenticator func(userId string, password string) bool

    // Callback function that should perform the authorization of the authenticated user. Called
    // only after an authentication success. Must return true on success, false on failure.
    // Optional, default to success.
    Authorizator func(userId string, request *Request) bool
}

AuthBasicMiddleware provides a simple AuthBasic implementation. On failure, a 401 HTTP response is returned. On success, the wrapped middleware is called, and the userId is made available as request.Env["REMOTE_USER"].(string)

func (*AuthBasicMiddleware) MiddlewareFunc Uses

func (mw *AuthBasicMiddleware) MiddlewareFunc(handler HandlerFunc) HandlerFunc

MiddlewareFunc makes AuthBasicMiddleware implement the Middleware interface.

type ContentTypeCheckerMiddleware Uses

type ContentTypeCheckerMiddleware struct{}

ContentTypeCheckerMiddleware verifies the request Content-Type header and returns a StatusUnsupportedMediaType (415) HTTP error response if it's incorrect. The expected Content-Type is 'application/json' if the content is non-null. Note: If a charset parameter exists, it MUST be UTF-8.

func (*ContentTypeCheckerMiddleware) MiddlewareFunc Uses

func (mw *ContentTypeCheckerMiddleware) MiddlewareFunc(handler HandlerFunc) HandlerFunc

MiddlewareFunc makes ContentTypeCheckerMiddleware implement the Middleware interface.

type CorsInfo Uses

type CorsInfo struct {
    IsCors      bool
    IsPreflight bool
    Origin      string
    OriginUrl   *url.URL

    // The header value is converted to uppercase to avoid common mistakes.
    AccessControlRequestMethod string

    // The header values are normalized with http.CanonicalHeaderKey.
    AccessControlRequestHeaders []string
}

CorsInfo contains the CORS request info derived from a rest.Request.

type CorsMiddleware Uses

type CorsMiddleware struct {

    // Reject non CORS requests if true. See CorsInfo.IsCors.
    RejectNonCorsRequests bool

    // Function excecuted for every CORS requests to validate the Origin. (Required)
    // Must return true if valid, false if invalid.
    // For instance: simple equality, regexp, DB lookup, ...
    OriginValidator func(origin string, request *Request) bool

    // List of allowed HTTP methods. Note that the comparison will be made in
    // uppercase to avoid common mistakes. And that the
    // Access-Control-Allow-Methods response header also uses uppercase.
    // (see CorsInfo.AccessControlRequestMethod)
    AllowedMethods []string

    // List of allowed HTTP Headers. Note that the comparison will be made with
    // noarmalized names (http.CanonicalHeaderKey). And that the response header
    // also uses normalized names.
    // (see CorsInfo.AccessControlRequestHeaders)
    AllowedHeaders []string

    // List of headers used to set the Access-Control-Expose-Headers header.
    AccessControlExposeHeaders []string

    // User to se the Access-Control-Allow-Credentials response header.
    AccessControlAllowCredentials bool

    // Used to set the Access-Control-Max-Age response header, in seconds.
    AccessControlMaxAge int
    // contains filtered or unexported fields
}

CorsMiddleware provides a configurable CORS implementation.

func (*CorsMiddleware) MiddlewareFunc Uses

func (mw *CorsMiddleware) MiddlewareFunc(handler HandlerFunc) HandlerFunc

MiddlewareFunc makes CorsMiddleware implement the Middleware interface.

type GzipMiddleware Uses

type GzipMiddleware struct{}

GzipMiddleware is responsible for compressing the payload with gzip and setting the proper headers when supported by the client. It must be wrapped by TimerMiddleware for the compression time to be captured. And It must be wrapped by RecorderMiddleware for the compressed BYTES_WRITTEN to be captured.

func (*GzipMiddleware) MiddlewareFunc Uses

func (mw *GzipMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes GzipMiddleware implement the Middleware interface.

type HandlerFunc Uses

type HandlerFunc func(ResponseWriter, *Request)

HandlerFunc defines the handler function. It is the go-json-rest equivalent of http.HandlerFunc.

func WrapMiddlewares Uses

func WrapMiddlewares(middlewares []Middleware, handler HandlerFunc) HandlerFunc

WrapMiddlewares calls the MiddlewareFunc methods in the reverse order and returns an HandlerFunc ready to be executed. This can be used to wrap a set of middlewares, post routing, on a per Route basis.

type IfMiddleware Uses

type IfMiddleware struct {

    // Runtime condition that decides of the execution of IfTrue of IfFalse.
    Condition func(r *Request) bool

    // Middleware to run when the condition is true. Note that the middleware is initialized
    // weather if will be used or not. (Optional, pass-through if not set)
    IfTrue Middleware

    // Middleware to run when the condition is false. Note that the middleware is initialized
    // weather if will be used or not. (Optional, pass-through if not set)
    IfFalse Middleware
}

IfMiddleware evaluates at runtime a condition based on the current request, and decides to execute one of the other Middleware based on this boolean.

func (*IfMiddleware) MiddlewareFunc Uses

func (mw *IfMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes TimerMiddleware implement the Middleware interface.

type JsonIndentMiddleware Uses

type JsonIndentMiddleware struct {

    // prefix string, as in json.MarshalIndent
    Prefix string

    // indentation string, as in json.MarshalIndent
    Indent string
}

JsonIndentMiddleware provides JSON encoding with indentation. It could be convenient to use it during development. It works by "subclassing" the responseWriter provided by the wrapping middleware, replacing the writer.EncodeJson and writer.WriteJson implementations, and making the parent implementations ignored.

func (*JsonIndentMiddleware) MiddlewareFunc Uses

func (mw *JsonIndentMiddleware) MiddlewareFunc(handler HandlerFunc) HandlerFunc

MiddlewareFunc makes JsonIndentMiddleware implement the Middleware interface.

type JsonpMiddleware Uses

type JsonpMiddleware struct {

    // Name of the query string parameter used to specify the
    // the name of the JS callback used for the padding.
    // Defaults to "callback".
    CallbackNameKey string
}

JsonpMiddleware provides JSONP responses on demand, based on the presence of a query string argument specifying the callback name.

func (*JsonpMiddleware) MiddlewareFunc Uses

func (mw *JsonpMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc returns a HandlerFunc that implements the middleware.

type Middleware Uses

type Middleware interface {
    MiddlewareFunc(handler HandlerFunc) HandlerFunc
}

Middleware defines the interface that objects must implement in order to wrap a HandlerFunc and be used in the middleware stack.

type MiddlewareSimple Uses

type MiddlewareSimple func(handler HandlerFunc) HandlerFunc

MiddlewareSimple is an adapter type that makes it easy to write a Middleware with a simple function. eg: api.Use(rest.MiddlewareSimple(func(h HandlerFunc) Handlerfunc { ... }))

func (MiddlewareSimple) MiddlewareFunc Uses

func (ms MiddlewareSimple) MiddlewareFunc(handler HandlerFunc) HandlerFunc

MiddlewareFunc makes MiddlewareSimple implement the Middleware interface.

type PoweredByMiddleware Uses

type PoweredByMiddleware struct {

    // If specified, used as the value for the "X-Powered-By" response header.
    // Defaults to "go-json-rest".
    XPoweredBy string
}

PoweredByMiddleware adds the "X-Powered-By" header to the HTTP response.

func (*PoweredByMiddleware) MiddlewareFunc Uses

func (mw *PoweredByMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes PoweredByMiddleware implement the Middleware interface.

type RecorderMiddleware Uses

type RecorderMiddleware struct{}

RecorderMiddleware keeps a record of the HTTP status code of the response, and the number of bytes written. The result is available to the wrapping handlers as request.Env["STATUS_CODE"].(int), and as request.Env["BYTES_WRITTEN"].(int64)

func (*RecorderMiddleware) MiddlewareFunc Uses

func (mw *RecorderMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes RecorderMiddleware implement the Middleware interface.

type RecoverMiddleware Uses

type RecoverMiddleware struct {

    // Custom logger used for logging the panic errors,
    // optional, defaults to log.New(os.Stderr, "", 0)
    Logger *log.Logger

    // If true, the log records will be printed as JSON. Convenient for log parsing.
    EnableLogAsJson bool

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

RecoverMiddleware catches the panic errors that occur in the wrapped HandleFunc, and convert them to 500 responses.

func (*RecoverMiddleware) MiddlewareFunc Uses

func (mw *RecoverMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes RecoverMiddleware implement the Middleware interface.

type Request Uses

type Request struct {
    *http.Request

    // Map of parameters that have been matched in the URL Path.
    PathParams map[string]string

    // Environment used by middlewares to communicate.
    Env map[string]interface{}
}

Request inherits from http.Request, and provides additional methods.

func (*Request) BaseUrl Uses

func (r *Request) BaseUrl() *url.URL

BaseUrl returns a new URL object with the Host and Scheme taken from the request. (without the trailing slash in the host)

func (*Request) DecodeJsonPayload Uses

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

DecodeJsonPayload reads the request body and decodes the JSON using json.Unmarshal.

func (*Request) GetCorsInfo Uses

func (r *Request) GetCorsInfo() *CorsInfo

GetCorsInfo derives CorsInfo from Request.

func (*Request) PathParam Uses

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

PathParam provides a convenient access to the PathParams map.

func (*Request) UrlFor Uses

func (r *Request) UrlFor(path string, queryParams map[string][]string) *url.URL

UrlFor returns the URL object from UriBase with the Path set to path, and the query string built with queryParams.

type ResponseWriter Uses

type ResponseWriter interface {

    // Identical to the http.ResponseWriter interface
    Header() http.Header

    // Use EncodeJson to generate the payload, write the headers with http.StatusOK if
    // they are not already written, then write the payload.
    // The Content-Type header is set to "application/json", unless already specified.
    WriteJson(v interface{}) error

    // Encode the data structure to JSON, mainly used to wrap ResponseWriter in
    // middlewares.
    EncodeJson(v interface{}) ([]byte, error)

    // Similar to the http.ResponseWriter interface, with additional JSON related
    // headers set.
    WriteHeader(int)
}

A ResponseWriter interface dedicated to JSON HTTP response. Note, the responseWriter object instantiated by the framework also implements many other interfaces accessible by type assertion: http.ResponseWriter, http.Flusher, http.CloseNotifier, http.Hijacker.

type Route Uses

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:
    // :paramName that matches any char to the first '/' or '.'
    // #paramName that matches any char to the first '/'
    // *paramName that matches everything to the end of the string
    // (placeholder names must be unique per PathExp)
    PathExp string

    // Code that will be executed when this route is taken.
    Func HandlerFunc
}

Route defines a route as consumed by the router. It can be instantiated directly, or using one of the shortcut methods: rest.Get, rest.Post, rest.Put, rest.Patch and rest.Delete.

func Delete Uses

func Delete(pathExp string, handlerFunc HandlerFunc) *Route

Delete is a shortcut method that instantiates a DELETE route. Equivalent to &Route{"DELETE", pathExp, handlerFunc}

func Get Uses

func Get(pathExp string, handlerFunc HandlerFunc) *Route

Get is a shortcut method that instantiates a GET route. See the Route object the parameters definitions. Equivalent to &Route{"GET", pathExp, handlerFunc}

func Head(pathExp string, handlerFunc HandlerFunc) *Route

Head is a shortcut method that instantiates a HEAD route. See the Route object the parameters definitions. Equivalent to &Route{"HEAD", pathExp, handlerFunc}

func Options Uses

func Options(pathExp string, handlerFunc HandlerFunc) *Route

Options is a shortcut method that instantiates an OPTIONS route. See the Route object the parameters definitions. Equivalent to &Route{"OPTIONS", pathExp, handlerFunc}

func Patch Uses

func Patch(pathExp string, handlerFunc HandlerFunc) *Route

Patch is a shortcut method that instantiates a PATCH route. See the Route object the parameters definitions. Equivalent to &Route{"PATCH", pathExp, handlerFunc}

func Post Uses

func Post(pathExp string, handlerFunc HandlerFunc) *Route

Post is a shortcut method that instantiates a POST route. See the Route object the parameters definitions. Equivalent to &Route{"POST", pathExp, handlerFunc}

func Put Uses

func Put(pathExp string, handlerFunc HandlerFunc) *Route

Put is a shortcut method that instantiates a PUT route. See the Route object the parameters definitions. Equivalent to &Route{"PUT", pathExp, handlerFunc}

func (*Route) MakePath Uses

func (route *Route) MakePath(pathParams map[string]string) string

MakePath generates the path corresponding to this Route and the provided path parameters. This is used for reverse route resolution.

type Status Uses

type Status struct {
    Pid                    int
    UpTime                 string
    UpTimeSec              float64
    Time                   string
    TimeUnix               int64
    StatusCodeCount        map[string]int
    TotalCount             int
    TotalResponseTime      string
    TotalResponseTimeSec   float64
    AverageResponseTime    string
    AverageResponseTimeSec float64
}

Status contains stats and status information. It is returned by GetStatus. These information can be made available as an API endpoint, see the "status" example to install the following status route. 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
}

type StatusMiddleware Uses

type StatusMiddleware struct {
    // contains filtered or unexported fields
}

StatusMiddleware keeps track of various stats about the processed requests. It depends on request.Env["STATUS_CODE"] and request.Env["ELAPSED_TIME"], recorderMiddleware and timerMiddleware must be in the wrapped middlewares.

func (*StatusMiddleware) GetStatus Uses

func (mw *StatusMiddleware) GetStatus() *Status

GetStatus computes and returns a Status object based on the request informations accumulated since the start of the process.

func (*StatusMiddleware) MiddlewareFunc Uses

func (mw *StatusMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes StatusMiddleware implement the Middleware interface.

type TimerMiddleware Uses

type TimerMiddleware struct{}

TimerMiddleware computes the elapsed time spent during the execution of the wrapped handler. The result is available to the wrapping handlers as request.Env["ELAPSED_TIME"].(*time.Duration), and as request.Env["START_TIME"].(*time.Time)

func (*TimerMiddleware) MiddlewareFunc Uses

func (mw *TimerMiddleware) MiddlewareFunc(h HandlerFunc) HandlerFunc

MiddlewareFunc makes TimerMiddleware implement the Middleware interface.

Directories

PathSynopsis
testUtility functions to help writing tests for a Go-Json-Rest app
trieSpecial Trie implementation for HTTP routing.

Package rest imports 21 packages (graph) and is imported by 333 packages. Updated 2017-09-13. Refresh now. Tools for package owners.