Documentation
¶
Overview ¶
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 URL routing using a Trie based implementation, helpers to deal with JSON requests and responses, and middlewares for additional functionalities like CORS, Auth, Gzip ...
Example:
package main
import (
"github.com/ant0ine/go-json-rest/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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Error ¶
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 ¶
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)
Types ¶
type AuthBasicMiddleware ¶
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
}
AuthBasicMiddleware provides a simple AuthBasic implementation. It can be used before routing to protect all the endpoints, see PreRoutingMiddlewares. Or it can be used to wrap a particular endpoint HandlerFunc.
func (*AuthBasicMiddleware) MiddlewareFunc ¶
func (mw *AuthBasicMiddleware) MiddlewareFunc(handler HandlerFunc) HandlerFunc
MiddlewareFunc tries to authenticate the user. It sends a 401 on failure, and executes the wrapped handler on success. Note that, on success, the userId is made available in the environment at request.Env["REMOTE_USER"]
type CorsInfo ¶
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 ¶
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 ¶
func (mw *CorsMiddleware) MiddlewareFunc(handler HandlerFunc) HandlerFunc
MiddlewareFunc makes CorsMiddleware implement the Middleware interface.
type HandlerFunc ¶
type HandlerFunc func(ResponseWriter, *Request)
HandlerFunc defines the handler function. It is the go-json-rest equivalent of http.HandlerFunc.
func WrapMiddlewares ¶
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 Middleware ¶
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 Request ¶
type Request struct {
*http.Request
// Map of parameters that have been matched in the URL Path.
PathParams map[string]string
// Environement used by middlewares to communicate.
Env map[string]interface{}
}
Request inherits from http.Request, and provides additional methods.
func (*Request) BaseUrl ¶
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 ¶
DecodeJsonPayload reads the request body and decodes the JSON using json.Unmarshal.
func (*Request) GetCorsInfo ¶
GetCorsInfo derives CorsInfo from Request.
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 records logged to the access log and the error log will be
// printed as JSON. Convenient for log parsing.
EnableLogAsJson bool
// If true, the handler does NOT check the request Content-Type. Otherwise, it
// must be set to 'application/json' if the content is non-null.
// Note: If a charset parameter exists, it MUST be UTF-8
EnableRelaxedContentType bool
// Optional global middlewares that can be used to wrap the all REST endpoints.
// They are used in the defined order, the first wrapping the second, ...
// They are run first, wrapping all go-json-rest middlewares,
// * request.PathParams is not set yet
// * "panic" won't be caught and converted to 500
// * request.Env["STATUS_CODE"] and request.Env["ELAPSED_TIME"] are set.
// They can be used for extra logging, or reporting.
// (see statsd example in in https://github.com/ant0ine/go-json-rest-examples)
OuterMiddlewares []Middleware
// Optional global middlewares that can be used to wrap the all REST endpoints.
// They are used in the defined order, the first wrapping the second, ...
// They are run pre REST routing, request.PathParams is not set yet.
// They are run post auto error handling, "panic" will be converted to 500 errors.
// They can be used for instance to manage CORS or authentication.
// (see the CORS and Auth examples in https://github.com/ant0ine/go-json-rest-examples)
PreRoutingMiddlewares []Middleware
// Custom logger for the access log,
// optional, defaults to log.New(os.Stderr, "", 0)
Logger *log.Logger
// If true, the access log will be fully disabled.
// (the log middleware is not even instantiated, avoiding any performance penalty)
DisableLogger bool
// Custom logger used for logging the panic errors,
// optional, defaults to log.New(os.Stderr, "", 0)
ErrorLogger *log.Logger
// Custom X-Powered-By value, defaults to "go-json-rest".
XPoweredBy string
// If true, the X-Powered-By header will NOT be set.
DisableXPoweredBy bool
// contains filtered or unexported fields
}
ResourceHandler implements the http.Handler interface and acts 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 for instance.
func (*ResourceHandler) GetStatus ¶
func (rh *ResourceHandler) GetStatus() *Status
GetStatus returns a Status object. EnableStatusService must be true.
func (*ResourceHandler) ServeHTTP ¶
func (rh *ResourceHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
This makes ResourceHandler implement the http.Handler interface. You probably don't want to use it directly.
func (*ResourceHandler) SetRoutes ¶
func (rh *ResourceHandler) SetRoutes(routes ...*Route) error
SetRoutes defines the Routes. The order the Routes matters, if a request matches multiple Routes, the first one will be used.
type ResponseWriter ¶
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 that the object instantiated by the ResourceHandler that implements this interface, also happens to implement http.ResponseWriter, http.Flusher and http.CloseNotifier.
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:
// :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. It's used with SetRoutes.
func RouteObjectMethod ¶
func RouteObjectMethod(httpMethod string, pathExp string, objectInstance interface{}, objectMethod string) *Route
RouteObjectMethod creates 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.
DEPRECATED: Since Go 1.1 and the introduction of the Method Values, this is now useless, and will probably be removed from the next major version of go-json-rest (v3) See: https://golang.org/doc/go1.1#method_values
type Status ¶
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
}
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Utility functions to help writing tests for a Go-Json-Rest app Go comes with net/http/httptest to help writing test for an http server.
|
Utility functions to help writing tests for a Go-Json-Rest app Go comes with net/http/httptest to help writing test for an http server. |
|
Special Trie implementation for HTTP routing.
|
Special Trie implementation for HTTP routing. |