gopkg.in/emicklei/go-restful.v1 (go): Package restful, a lean package for creating REST-style WebServices without magic.  A WebService has a collection of Route objects that dispatch incoming Http Requests to a function calls. Typically, a WebService has a root path (e.g. /users) and defines common MIME types for its routes. WebServices must be added to a container (see below) in order to handler Http requests from a server.  A Route is defined by a HTTP method, an URL path and (optionally) the MIME types it consumes (Content-Type) and produces (Accept). This package has the logic to find the best matching Route and if found, call its Function.  The (*Request, *Response) arguments provide functions for reading information from the request and writing information back to the response.  See the example https://github.com/emicklei/go-restful/blob/master/examples/restful-user-resource.go with a full implementation.  A Route parameter can be specified using the format "uri/{var[:regexp]}" or the special version "uri/{var:*}" for matching the tail of the path. For example, /persons/{name:[A-Z][A-Z]} can be used to restrict values for the parameter "name" to only contain capital alphabetic characters. Regular expressions must use the standard Go syntax as described in the regexp package. (https://code.google.com/p/re2/wiki/Syntax) This feature requires the use of a CurlyRouter.  A Container holds a collection of WebServices, Filters and a http.ServeMux for multiplexing http requests. Using the statements "restful.Add(...) and restful.Filter(...)" will register WebServices and Filters to the Default Container. The Default container of go-restful uses the http.DefaultServeMux. You can create your own Container and create a new http.Server for that particular container.  A filter dynamically intercepts requests and responses to transform or use the information contained in the requests or responses. You can use filters to perform generic logging, measurement, authentication, redirect, set response headers etc. In the restful package there are three hooks into the request,response flow where filters can be added. Each filter must define a FilterFunction:  Use the following statement to pass the request,response pair to the next filter or RouteFunction  These are processed before any registered WebService.  These are processed before any Route of a WebService.  These are processed before calling the function associated with the Route.  See the example https://github.com/emicklei/go-restful/blob/master/examples/restful-filters.go with full implementations.  Two encodings are supported: gzip and deflate. To enable this for all responses:  If a Http request includes the Accept-Encoding header then the response content will be compressed using the specified encoding. Alternatively, you can create a Filter that performs the encoding and install it per WebService or Route.  See the example https://github.com/emicklei/go-restful/blob/master/examples/restful-encoding-filter.go  By installing a pre-defined container filter, your Webservice(s) can respond to the OPTIONS Http request.  By installing the filter of a CrossOriginResourceSharing (CORS), your WebService(s) can handle CORS requests.  Unexpected things happen. If a request cannot be processed because of a failure, your service needs to tell via the response what happened and why. For this reason HTTP status codes exist and it is important to use the correct code in every exceptional situation.  If path or query parameters are not valid (content or type) then use http.StatusBadRequest.  Despite a valid URI, the resource requested may not be available  If the application logic could not process the request (or write the response) then use http.StatusInternalServerError.  The request has a valid URL but the method (GET,PUT,POST,...) is not allowed.  The request does not have or has an unknown Accept Header set for this operation.  The request does not have or has an unknown Content-Type Header set for this operation.  In addition to setting the correct (error) Http status code, you can choose to write a ServiceError message on the response.  This package has several options that affect the performance of your service. It is important to understand them and how you can change it.  The default router is the RouterJSR311 which is an implementation of its spec (http://jsr311.java.net/nonav/releases/1.1/spec/spec.html). However, it uses regular expressions for all its routes which, depending on your usecase, may consume a significant amount of time. The CurlyRouter implementation is more lightweight that also allows you to use wildcards and expressions, but only if needed.  DoNotRecover controls whether panics will be caught to return HTTP 500. If set to true, Route functions are responsible for handling any error situation. Default value is false; it will recover from panics. This has performance implications.  SetCacheReadEntity controls whether the response data ([]byte) is cached such that ReadEntity is repeatable. If you expect to read large amounts of payload data, and you do not use this feature, you should set it to false.  This package has the means to produce detail logging of the complete Http request matching process and filter invocation. Enabling this feature requires you to set a log.Logger instance such as:  (c) 2012-2014, http://ernestmicklei.com. MIT License
Keywords: customizable|go|openapi|rest|routing