go-restful

As of version v3.0.0, go-restful supports Go modules. Import the package using the /v3 suffix in your import statement.

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

The package provides several hooks for customization:

• Router: Change the routing algorithm.
• Panic Recovery: Use RecoverHandler(...) to customize how panics are handled.
• Error Handling: Use ServiceErrorHandler(...) to customize route errors.
• Encoding/Compression: Register custom JSON decoders, EntityReaderWriter for new serializers, or CompressorProvider for custom gzip/deflate behavior.
• Logging: Configure trace logging.
• Slash Matching: Control whether routes ending in a slash / match using the TrimRightSlashEnabled package variable (defaults to true).

For versions up to v2.*.*, use the following import path which does not include the version suffix.

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

You can build RESTful services by creating a restful.WebService instance, defining its base path, supported media types (Consumes/Produces), and registering routes that map HTTP methods and paths to handler functions.

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{}))

// Handler implementation
func (u UserResource) findUser(request *restful.Request, response *restful.Response) {
	id := request.PathParameter("user-id")
	...
}

The global variable restful.EnableContentEncoding is OBSOLETE.

Instead of toggling this variable, use restful.DefaultContainer.EnableContentEncoding(true) to change the content encoding setting in your container.

The Do method allows you to apply a set of configuration steps to a RouteBuilder using a reusable function. This helps follow DRY (Don't Repeat Yourself) principles when multiple routes share common documentation or response patterns.

// Reusable configuration block
func StandardErrors(b *restful.RouteBuilder) {
    b.Returns(500, "Internal Server Error", ErrorModel{})
    b.Returns(401, "Unauthorized", nil)
}

// Usage in route definition
ws.Route(ws.GET("/").To(myHandler).Do(StandardErrors))

ws.Route(ws.DELETE("/{name}").To(t.deletePerson).Do(Returns200, Returns500))

func Returns500(b *RouteBuilder) {
    b.Returns(500, "Internal Server Error", restful.ServiceError{})
}

The Parameter type allows you to set detailed metadata and validation constraints for your API documentation:

• Basic Metadata: Description(string), DataType(string), DataFormat(string), DefaultValue(string).
• Validation: Pattern(string), Minimum(float64), Maximum(float64), MinLength(int64), MaxLength(int64), MinItems(int64), MaxItems(int64), UniqueItems(bool).
• Requirement & Multiplicity: Required(bool), AllowMultiple(bool), AllowEmptyValue(bool).
• Values: PossibleValues([]string) sets a list of allowed values. (Note: AllowableValues(map[string]string) is deprecated but still functional and maps to PossibleValues).

By default, the DefaultContainer recovers from panics and returns an HTTP 500 error. To disable this behavior (which may improve performance but requires Route functions to handle all errors manually), use the DoNotRecover(true) method on the DefaultContainer instance.

Note: The package-level variable DoNotRecover is obsolete.

restful.DefaultContainer.DoNotRecover(true)