package for building REST-style Web Services using Google Go
Clone or download
Latest commit 8ec491e Dec 6, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Fix Comments of Update and Create User (#385) Dec 6, 2018
log apply lint hints Feb 16, 2017
.gitignore fix Issue #111 too many WriteHeader calls Apr 14, 2014
.travis.yml add make for travis Feb 16, 2017
CHANGES.md update doc wrt jsoniter Jul 1, 2018
LICENSE add comment and change Jun 3, 2013
Makefile add make for travis Feb 16, 2017
README.md update doc wrt jsoniter Jul 1, 2018
Srcfile skip examples dir in Sourcegraph/srclib build Sep 18, 2014
bench_curly_test.go updated CHANGES because constant renaming changes api Feb 17, 2014
bench_test.go fixed benchmark tests, add comment to pre-post, replaced "self" as re… Oct 8, 2013
bench_test.sh updated docs, add bench for curlyrouter Sep 12, 2013
compress.go Remove fmt.Errorf call and use errors.New instead Feb 2, 2016
compress_test.go Remove SetCacheReadEntity Dec 22, 2016
compressor_cache.go update docs about compressorprovider Sep 18, 2015
compressor_pools.go Put acquired resources back to pool Nov 17, 2015
compressors.go Use proper formatting for comments to make go doc happy Jul 1, 2017
constants.go Issue #170, better handle missing Content-Type Mar 20, 2015
container.go logging: Remove redundant [restful] prefixes (#381) Jul 26, 2018
container_test.go added test + fixed remove May 7, 2016
cors_filter.go cors filter support regex check against allowd origin May 4, 2016
cors_filter_test.go expose Dispatch on Container for tests Jan 29, 2017
coverage.sh fixes Issue #137 , added tests for both routers, updated coverage script Aug 23, 2014
curly.go Issue #306, part of v2 Nov 26, 2016
curly_route.go alloc optimiz. in curly router May 11, 2016
curly_test.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
doc.go apply lint hints Feb 16, 2017
doc_examples_test.go update docs Sep 28, 2015
entity_accessors.go add json-iterator for go-restful (#379), (requires build tag to enabl… Jul 1, 2018
entity_accessors_test.go Use named fields in the Response struct initialization Sep 19, 2017
filter.go add NoBrowserCacheFilter Nov 23, 2016
filter_test.go fixed benchmark tests, add comment to pre-post, replaced "self" as re… Oct 8, 2013
json.go add json-iterator for go-restful (#379), (requires build tag to enabl… Jul 1, 2018
jsoniter.go add json-iterator for go-restful (#379), (requires build tag to enabl… Jul 1, 2018
jsr311.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
jsr311_test.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
logger.go Use proper formatting for comments to make go doc happy Jul 1, 2017
mime.go parse quality to float of mime spec Feb 14, 2016
mime_test.go parse quality to float of mime spec Feb 14, 2016
options_filter.go Additional CORS headers for OPTIONS request + remove old example Sep 17, 2017
options_filter_test.go fixed issue #59 + disallow duplicate root path of webservices Oct 6, 2013
parameter.go Add CollectionFormat to Parameter type. When used with AllowMultiple(… Oct 4, 2017
path_expression.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
path_expression_test.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
path_processor.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
path_processor_test.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
request.go Add a new method Request.QueryParameters() to retrieve multiple values ( Jun 5, 2018
request_test.go Add a new method Request.QueryParameters() to retrieve multiple values ( Jun 5, 2018
response.go Expose http.Hijacker Sep 19, 2017
response_test.go add json-iterator for go-restful (#379), (requires build tag to enabl… Jul 1, 2018
route.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
route_builder.go logging: Remove redundant [restful] prefixes (#381) Jul 26, 2018
route_builder_test.go add DefaultReturns to RouteBuilder emicklei/go-restful-openapi#10 Mar 27, 2017
route_test.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
router.go Make JSR 311 routing and path param processing consistent (#366) Jan 28, 2018
service_error.go more lint stuff Oct 20, 2013
tracer_test.go extra test case for multi produce mime May 22, 2015
web_service.go logging: Remove redundant [restful] prefixes (#381) Jul 26, 2018
web_service_container.go Make ServeMux public. Jul 10, 2014
web_service_test.go Adding description to RouteBuilder.Reads() Oct 25, 2017

README.md

go-restful

package for building REST-style Web Services using Google Go

Build Status Go Report Card GoDoc

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:

  • GET = Retrieve a representation of a resource
  • POST = Create if you are sending content to the server to create a subordinate of the specified resource collection, using some server-side algorithm.
  • PUT = Create if you are sending the full content of the specified resource (URI).
  • PUT = Update if you are updating the full content of the specified resource.
  • DELETE = Delete if you are requesting the server to delete the resource
  • PATCH = Update partial content of a resource
  • OPTIONS = Get information about the communication options for the request URI

Example

ws := new(restful.WebService)
ws.
	Path("/users").
	Consumes(restful.MIME_XML, restful.MIME_JSON).
	Produces(restful.MIME_JSON, restful.MIME_XML)

ws.Route(ws.GET("/{user-id}").To(u.findUser).
	Doc("get a user").
	Param(ws.PathParameter("user-id", "identifier of the user").DataType("string")).
	Writes(User{}))		
...
	
func (u UserResource) findUser(request *restful.Request, response *restful.Response) {
	id := request.PathParameter("user-id")
	...
}

Full API of a UserResource

Features

  • Routes for request → function mapping with path parameter (e.g. {id}) support
  • Configurable router:
    • (default) Fast routing algorithm that allows static elements, regular expressions and dynamic parameters in the URL path (e.g. /meetings/{id} or /static/{subpath:*}
    • Routing algorithm after JSR311 that is implemented using (but does not accept) regular expressions
  • Request API for reading structs from JSON/XML and accesing parameters (path,query,header)
  • Response API for writing structs to JSON/XML and setting headers
  • Customizable encoding using EntityReaderWriter registration
  • Filters for intercepting the request → response flow on Service or Route level
  • Request-scoped variables using attributes
  • Containers for WebServices on different HTTP endpoints
  • Content encoding (gzip,deflate) of request and response payloads
  • Automatic responses on OPTIONS (using a filter)
  • Automatic CORS request handling (using a filter)
  • API declaration for Swagger UI (go-restful-openapi, see go-restful-swagger12)
  • Panic recovery to produce HTTP 500, customizable using RecoverHandler(...)
  • Route errors produce HTTP 404/405/406/415 errors, customizable using ServiceErrorHandler(...)
  • Configurable (trace) logging
  • Customizable gzip/deflate readers and writers using CompressorProvider registration

How to customize

There are several hooks to customize the behavior of the go-restful package.

  • Router algorithm
  • Panic recovery
  • JSON decoder
  • Trace logging
  • Compression
  • Encoders for other serializers
  • Use jsoniter by build this package using a tag, e.g. go build -tags=jsoniter .

TODO: write examples of these.

Resources

Type git shortlog -s for a full list of contributors.

© 2012 - 2018, http://ernestmicklei.com. MIT License. Contributions are welcome.