GitHub - emicklei/go-restful: package for building REST-style Web Services using Go (original) (raw)

go-restful

package for building REST-style Web Services using Google Go

Code examples use v3

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

Usage

Without Go Modules

All versions up to v2.*.* (on the master) are not supporting Go modules.

import (
    restful "github.com/emicklei/go-restful"
)

Using Go Modules

As of version v3.0.0 (on the v3 branch), this package supports Go modules.

import (
    restful "github.com/emicklei/go-restful/v3"
)

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} but also prefix_{var} and {var}_suffix) support
Configurable router:
- (default) Fast routing algorithm that allows static elements, google custom method, regular expressions and dynamic parameters in the URL path (e.g. /resource/name:customVerb, /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 accessing 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)
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
Inject your own http.Handler using the HttpMiddlewareHandlerToFilter function

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 the package variable TrimRightSlashEnabled (default true) to control the behavior of matching routes that end with a slash /

Resources

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