3 package for building REST-style Web Services using Google Go
5 [![Build Status](https://travis-ci.org/emicklei/go-restful.png)](https://travis-ci.org/emicklei/go-restful)
6 [![Go Report Card](https://goreportcard.com/badge/github.com/emicklei/go-restful)](https://goreportcard.com/report/github.com/emicklei/go-restful)
7 [![GoDoc](https://godoc.org/github.com/emicklei/go-restful?status.svg)](https://godoc.org/github.com/emicklei/go-restful)
9 - [Code examples](https://github.com/emicklei/go-restful/tree/master/examples)
11 REST asks developers to use HTTP methods explicitly and in a way that's consistent with the protocol definition. This basic REST design principle establishes a one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods. According to this mapping:
13 - GET = Retrieve a representation of a resource
14 - POST = Create if you are sending content to the server to create a subordinate of the specified resource collection, using some server-side algorithm.
15 - PUT = Create if you are sending the full content of the specified resource (URI).
16 - PUT = Update if you are updating the full content of the specified resource.
17 - DELETE = Delete if you are requesting the server to delete the resource
18 - PATCH = Update partial content of a resource
19 - OPTIONS = Get information about the communication options for the request URI
24 ws := new(restful.WebService)
27 Consumes(restful.MIME_XML, restful.MIME_JSON).
28 Produces(restful.MIME_JSON, restful.MIME_XML)
30 ws.Route(ws.GET("/{user-id}").To(u.findUser).
32 Param(ws.PathParameter("user-id", "identifier of the user").DataType("string")).
36 func (u UserResource) findUser(request *restful.Request, response *restful.Response) {
37 id := request.PathParameter("user-id")
42 [Full API of a UserResource](https://github.com/emicklei/go-restful/tree/master/examples/restful-user-resource.go)
46 - Routes for request → function mapping with path parameter (e.g. {id}) support
47 - Configurable router:
48 - (default) Fast routing algorithm that allows static elements, regular expressions and dynamic parameters in the URL path (e.g. /meetings/{id} or /static/{subpath:*}
49 - Routing algorithm after [JSR311](http://jsr311.java.net/nonav/releases/1.1/spec/spec.html) that is implemented using (but does **not** accept) regular expressions
50 - Request API for reading structs from JSON/XML and accesing parameters (path,query,header)
51 - Response API for writing structs to JSON/XML and setting headers
52 - Customizable encoding using EntityReaderWriter registration
53 - Filters for intercepting the request → response flow on Service or Route level
54 - Request-scoped variables using attributes
55 - Containers for WebServices on different HTTP endpoints
56 - Content encoding (gzip,deflate) of request and response payloads
57 - Automatic responses on OPTIONS (using a filter)
58 - Automatic CORS request handling (using a filter)
59 - API declaration for Swagger UI ([go-restful-openapi](https://github.com/emicklei/go-restful-openapi), see [go-restful-swagger12](https://github.com/emicklei/go-restful-swagger12))
60 - Panic recovery to produce HTTP 500, customizable using RecoverHandler(...)
61 - Route errors produce HTTP 404/405/406/415 errors, customizable using ServiceErrorHandler(...)
62 - Configurable (trace) logging
63 - Customizable gzip/deflate readers and writers using CompressorProvider registration
66 There are several hooks to customize the behavior of the go-restful package.
73 - Encoders for other serializers
74 - Use [jsoniter](https://github.com/json-iterator/go) by build this package using a tag, e.g. `go build -tags=jsoniter .`
76 TODO: write examples of these.
80 - [Example posted on blog](http://ernestmicklei.com/2012/11/go-restful-first-working-example/)
81 - [Design explained on blog](http://ernestmicklei.com/2012/11/go-restful-api-design/)
82 - [sourcegraph](https://sourcegraph.com/github.com/emicklei/go-restful)
83 - [showcase: Zazkia - tcp proxy for testing resiliency](https://github.com/emicklei/zazkia)
84 - [showcase: Mora - MongoDB REST Api server](https://github.com/emicklei/mora)
86 Type ```git shortlog -s``` for a full list of contributors.
88 © 2012 - 2018, http://ernestmicklei.com. MIT License. Contributions are welcome.