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/httpHandler. 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.
- Test package to help writing tests for the API.
- 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
(See the dedicated examples repository: https://github.com/ant0ine/go-json-rest-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
- GAE Demo go-json-rest on Google App Engine
- GORM Demo basic CRUD operations using MySQL and GORM
- Streaming Demo Line Delimited JSON stream
- CORS Demo CORS support for all endpoints
- Basic Auth Demo an Authentication Basic impl for all endpoints
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)
- Relaxed ContentType (default: disabled)
- 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
Copyright (c) 2013-2014 Antoine Imbert
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 *ResponseWriter, error string, code int)
- func NotFound(w *ResponseWriter, r *Request)
- type CorsInfo
- type HandlerFunc
- type Request
- func (self *Request) DecodeJsonPayload(v interface{}) error
- func (self *Request) GetCorsInfo() *CorsInfo
- 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
- type ResponseWriter
- type Route
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Error ¶
func Error(w *ResponseWriter, 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 *ResponseWriter, 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 CorsInfo ¶
type CorsInfo struct {
IsCors bool
IsPreflight bool
Origin string
OriginUrl *url.URL
AccessControlRequestMethod string
AccessControlRequestHeaders []string
}
CORS request info derived from a rest.Request.
type HandlerFunc ¶
type HandlerFunc func(*ResponseWriter, *Request)
Signature of a handler method in the context of go-json-rest.
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 ¶
Read the request body and decode the JSON using json.Unmarshal
func (*Request) GetCorsInfo ¶
Derive CorsInfo from Request
func (*Request) UriBase ¶
Returns a URL structure for the base (scheme + host) of the application, without the trailing slash in the host
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
// 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 middleware that can be used to wrap the REST endpoints.
// It can be used for instance to manage CORS or authentication.
// (see the CORS example in go-json-rest-example)
// This is run pre REST routing, request.PathParams is not set yet.
PreRoutingMiddleware func(handler HandlerFunc) HandlerFunc
// 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(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 (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 ResponseWriter ¶
type ResponseWriter struct {
http.ResponseWriter
// contains filtered or unexported fields
}
Inherit from an object implementing the http.ResponseWriter interface, and provide additional methods.
func (*ResponseWriter) CloseNotify ¶
func (self *ResponseWriter) CloseNotify() <-chan bool
Make rest.ResponseWriter implement the http.CloseNotifier interface.
func (*ResponseWriter) Flush ¶
func (self *ResponseWriter) Flush()
Make rest.ResponseWriter implement the http.Flusher interface. It propagates the Flush call to the wrapped ResponseWriter.
func (*ResponseWriter) WriteJson ¶
func (self *ResponseWriter) 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 HandlerFunc
}
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.
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. |