package for building REST-style Web Services using Google Go
Go Other
Latest commit cf834cf Feb 16, 2017 @emicklei update doc
Change-Id: Iadc3bad4aaf1565b4c9e0daa8dfa62ebe3bcf8a3
Permalink
Failed to load latest commit information.
examples apply lint hints Feb 16, 2017
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 add make for travis Feb 16, 2017
LICENSE add comment and change Jun 3, 2013
Makefile add make for travis Feb 16, 2017
README.md update doc Feb 16, 2017
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 apply lint hints Feb 16, 2017
constants.go Issue #170, better handle missing Content-Type Mar 20, 2015
container.go expose Dispatch on Container for tests Jan 29, 2017
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 fix remaining vet reported problems in tests Jun 29, 2016
doc.go apply lint hints Feb 16, 2017
doc_examples_test.go update docs Sep 28, 2015
entity_accessors.go constructor function for vendor types, Issue #266 Feb 14, 2016
entity_accessors_test.go tryout write with status Sep 25, 2015
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
jsr311.go alloc optimiz. in curly router May 11, 2016
jsr311_test.go fix issue #179 JSR311 router handling regular expression for parameter Feb 6, 2015
logger.go Add 'log' package for package-wide logging, expose SetLogger(Logger). Mar 20, 2015
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 add comment to OPTIONSFilter, Issue #27 Sep 22, 2015
options_filter_test.go fixed issue #59 + disallow duplicate root path of webservices Oct 6, 2013
parameter.go Adds format to Parameter in go-restful and use it for the Format in S… Oct 7, 2015
path_expression.go fix issue #179 JSR311 router handling regular expression for parameter Feb 6, 2015
path_expression_test.go fix issue #179 JSR311 router handling regular expression for parameter Feb 6, 2015
request.go Remove SetCacheReadEntity Dec 22, 2016
request_test.go Remove SetCacheReadEntity Dec 22, 2016
response.go apply lint hints Feb 16, 2017
response_test.go fix remaining vet reported problems in tests Jun 29, 2016
route.go Add metadata to Route Feb 11, 2017
route_builder.go issue #304 auto name operation to avoid validator errors Feb 16, 2017
route_builder_test.go issue #304 auto name operation to avoid validator errors Feb 16, 2017
route_test.go extra test case for multi produce mime May 22, 2015
router.go some doc love + work on curly bench Nov 28, 2013
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 Allow body parameter type name to be customized Dec 19, 2016
web_service_container.go Make ServeMux public. Jul 10, 2014
web_service_test.go Allow body parameter type name to be customized Dec 19, 2016

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 (see go-restful-swagger12,go-restful-openapi)
  • 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

Resources

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

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