cmd/bpa-operator/vendor/github.com/emicklei/go-restful/README.md

   1 go-restful
   2 ==========
   3 package for building REST-style Web Services using Google Go
   4
   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)
   8
   9 - [Code examples](https://github.com/emicklei/go-restful/tree/master/examples)
  10
  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:
  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
  24 ws := new(restful.WebService)
  25 ws.
  26         Path("/users").
  27         Consumes(restful.MIME_XML, restful.MIME_JSON).
  28         Produces(restful.MIME_JSON, restful.MIME_XML)
  29
  30 ws.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
  36 func (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 &#8594; 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 &#8594; 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
  66 There 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
  76 TODO: 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
  86 Type ```git shortlog -s``` for a full list of contributors.
  87
  88 © 2012 - 2018, http://ernestmicklei.com. MIT License. Contributions are welcome.