README.md
1go-restful
2==========
3package for building REST-style Web Services using Google Go
4
5[](https://travis-ci.org/emicklei/go-restful)
6[](https://goreportcard.com/report/github.com/emicklei/go-restful)
7[](https://godoc.org/github.com/emicklei/go-restful)
8
9- [Code examples](https://github.com/emicklei/go-restful/tree/master/examples)
10
11REST 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:
12
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
20
21### Example
22
23```Go
24ws := new(restful.WebService)
25ws.
26 Path("/users").
27 Consumes(restful.MIME_XML, restful.MIME_JSON).
28 Produces(restful.MIME_JSON, restful.MIME_XML)
29
30ws.Route(ws.GET("/{user-id}").To(u.findUser).
31 Doc("get a user").
32 Param(ws.PathParameter("user-id", "identifier of the user").DataType("string")).
33 Writes(User{}))
34...
35
36func (u UserResource) findUser(request *restful.Request, response *restful.Response) {
37 id := request.PathParameter("user-id")
38 ...
39}
40```
41
42[Full API of a UserResource](https://github.com/emicklei/go-restful/tree/master/examples/restful-user-resource.go)
43
44### Features
45
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
64
65## How to customize
66There are several hooks to customize the behavior of the go-restful package.
67
68- Router algorithm
69- Panic recovery
70- JSON decoder
71- Trace logging
72- Compression
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 .`
75
76TODO: write examples of these.
77
78## Resources
79
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)
85
86Type ```git shortlog -s``` for a full list of contributors.
87
88© 2012 - 2018, http://ernestmicklei.com. MIT License. Contributions are welcome.
89
){kind=link}
){kind=link}