go-restful is an MIT-licensed Go package for building REST-style web services in which the HTTP methods map one-to-one onto create, read, update and delete operations, and it is aimed at Go developers who want explicit, customizable control over routing, request parsing, response encoding and filter chains.

What it is

go-restful is a library in the Go ecosystem for building REST-style web services. It declares a WebService with Path, Consumes and Produces, registers routes that map an HTTP method and path to a handler function, and mounts those services on a Container. The project spans the routing layer, a Request API for reading structs from JSON or XML and for reading path, query and header parameters, a Response API for writing structs and setting headers, and a filter mechanism for intercepting the request-to-response flow. Its module path for current releases is github.com/emicklei/go-restful/v3, and its topic list is customizable, go, openapi, rest and routing.

The concrete problem it solves is dispatch: without it, a Go service has to hand-match HTTP verbs and URL paths to functions and hand-decode bodies before any handler logic runs. go-restful replaces that manual wiring with declarative routes such as ws.GET("/{user-id}").To(u.findUser) and ws.PathParameter("user-id", "identifier of the user").DataType("string"), along with the encoding and error handling around them. It also offers an API declaration path to Swagger UI through the companion project go-restful-openapi, so the same route definitions can feed generated documentation instead of a separately maintained specification.

Key capabilities

• Routes map a request to a function with path parameters in several forms: {id}, prefix_{var} and {var}_suffix.
• Configurable router: the default fast algorithm supports static elements, Google custom methods, regular expressions and dynamic parameters such as /resource/name:customVerb, /meetings/{id} and /static/{subpath:*}; an alternative algorithm after JSR311 is implemented using regular expressions but does not accept them in route definitions.
• Request API reads structs from JSON and XML and exposes path, query and header parameters; Response API writes structs to JSON and XML and sets headers, with encodings named as restful.MIME_XML and restful.MIME_JSON.
• Customizable encoding through EntityReaderWriter registration, and customizable gzip and deflate readers and writers through CompressorProvider registration.
• Filters intercept the request-to-response flow at either Service or Route level, and request-scoped variables are held in attributes.
• Container type hosts WebServices on different HTTP endpoints, and content encoding (gzip, deflate) applies to request and response payloads.
• Panic recovery produces an HTTP 500 customizable via RecoverHandler(...), while route errors produce HTTP 404, 405, 406 or 415 customizable via ServiceErrorHandler(...); automatic OPTIONS responses and automatic CORS handling are available as filters.

Who uses it and how

• Go teams building HTTP APIs who prefer explicit route declarations over a larger framework, using WebService, Route and Container to structure handlers.
• Projects that need generated OpenAPI or Swagger UI output, adopting go-restful-openapi alongside the routes they already declared.
• Services exposing several HTTP endpoints side by side, using one Container per endpoint rather than a single global mux.
• Services that must serve both JSON and XML, or that need gzip and deflate request and response payloads, configuring this per WebService with Consumes and Produces.
• Codebases moving onto Go modules, which must be on the v3 major version because versions up to v2.*.* on master do not support modules.

Getting started

Go modules users import the package as restful "github.com/emicklei/go-restful/v3", which is supported as of version v3.0.0 on the v3 branch. Previously it was imported as restful "github.com/emicklei/go-restful" without modules, and working code examples for v3 live in the repository's examples directory.

How it compares

No list of paid products replaced by this project is provided, so a comparison on licence, self-hosting, data ownership and cost model cannot be made from the available facts. Among similar tools, the facts name only go-restful-openapi, which is a companion library for API declaration rather than an alternative; otherwise go-restful stands alone in this registry.

When to use it — and when not to

This is a library rather than a hosted service, so a self-hoster operates no database, object storage or SMTP component on its behalf — the operational burden is the Go process and whatever infrastructure the surrounding application already uses. Teams that want a framework supplying templating, persistence and administrative scaffolding should look elsewhere, because the README covers routing, encoding, filters and error handling and stops there. Pick v3 deliberately when moving to Go modules, since the master-line versions up to v2.*.* do not support them, and note that the customization section of the README is presented as a list of hooks rather than as worked configuration examples.

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

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

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")
	...
}