Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


Package httprequest provides functionality for unmarshaling HTTP request parameters into a struct type. Please note that the API is not considered stable at this point and may be changed in a backwardly incompatible manner at any time.


Version published


# httprequest
    import ""

Package httprequest provides functionality for unmarshaling HTTP request
parameters into a struct type.

Please note that the API is not considered stable at this point and may be
changed in a backwardly incompatible manner at any time.

## Usage

var (
	ErrUnmarshal        = errgo.New("httprequest unmarshal error")
	ErrBadUnmarshalType = errgo.New("httprequest bad unmarshal type")

#### func  Marshal

func Marshal(baseURL, method string, x interface{}) (*http.Request, error)
Marshal is the counterpart of Unmarshal. It takes information from x, which must
be a pointer to a struct, and returns an HTTP request using the given method
that holds all of the information

The HTTP request will use the given method. Named fields in the given baseURL
will be filled out from "path"-tagged fields in x to form the URL path in the
returned request. These are specified as for httprouter.

If a field in baseURL is a suffix of the form "*var" (a trailing wildcard
element that holds the rest of the path), the marshaled string must begin with a
"/". This matches the httprouter convention that it always returns such fields
with a "/" prefix.

If a field is of type string or []string, the value of the field will be used
directly; otherwise if implements encoding.TextMarshaler, that will be used to
marshal the field, otherwise fmt.Sprint will be used.

For example, this code:

    type UserDetails struct {
        Age int

    type Test struct {
        Username string `httprequest:"user,path"`
        ContextId int64 `httprequest:"context,form"`
        Details UserDetails `httprequest:",body"`
    req, err := Marshal("GET", "", &Test{
        Username: "bob",
        ContextId: 1234,
        Details: UserDetails{
            Age: 36,
    if err != nil {

will produce an HTTP request req with a URL of and a JSON-encoded body
holding `{"Age":36}`.

It is an error if there is a field specified in the URL that is not found in x.

#### func  ToHTTP

func ToHTTP(h httprouter.Handle) http.Handler
ToHTTP converts an httprouter.Handle into an http.Handler. It will pass no path
variables to h.

#### func  Unmarshal

func Unmarshal(p Params, x interface{}) error
Unmarshal takes values from given parameters and fills out fields in x, which
must be a pointer to a struct.

Tags on the struct's fields determine where each field is filled in from.
Similar to encoding/json and other encoding packages, the tag holds a
comma-separated list. The first item in the list is an alternative name for the
field (the field name itself will be used if this is empty). The next item
specifies where the field is filled in from. It may be:

    "path" - the field is taken from a parameter in p.PathVar
    	with a matching field name.

    "form" - the field is taken from the given name in p.Form
    	(note that this covers both URL query parameters and
    	POST form parameters)

    "body" - the field is filled in by parsing the request body
    	as JSON.

For path and form parameters, the field will be filled out from the field in
p.PathVar or p.Form using one of the following methods (in descending order of

- if the type is string, it will be set from the first value.

- if the type is []string, it will be filled out using all values for that field

    (allowed only for form)

- if the type implements encoding.TextUnmarshaler, its UnmarshalText method will
be used

- otherwise fmt.Sscan will be used to set the value.

When the unmarshaling fails, Unmarshal returns an error with an ErrUnmarshal
cause. If the type of x is inappropriate, it returns an error with an
ErrBadUnmarshalType cause.

#### func  WriteJSON

func WriteJSON(w http.ResponseWriter, code int, val interface{}) error
WriteJSON writes the given value to the ResponseWriter and sets the HTTP status
to the given code.

#### type ErrorHandler

type ErrorHandler func(http.ResponseWriter, Params) error

ErrorHandler is like httprouter.Handle except it returns an error which may be
returned as the error body of the response. An ErrorHandler function should not
itself write to the ResponseWriter if it returns an error.

#### type ErrorMapper

type ErrorMapper func(err error) (httpStatus int, errorBody interface{})

ErrorMapper holds a function that can convert a Go error into a form that can be
returned as a JSON body from an HTTP request. The httpStatus value reports the
desired HTTP status.

#### func (ErrorMapper) Handle

func (e ErrorMapper) Handle(f interface{}) httprouter.Handle
Handle converts a function into an httprouter.Handle. The argument f must be a
function of one of the following three forms, where ArgT must be a struct type
acceptable to Unmarshal and ResultT is a type that can be marshaled as JSON:

    func(w http.ResponseWriter, p Params, arg *ArgT)
    func(w http.ResponseWriter, p Params, arg *ArgT) error
    func(header http.Header, p Params, arg *ArgT) (ResultT, error)

When processing a call to the returned handler, the provided parameters are
unmarshaled into a new ArgT value using Unmarshal, then f is called with this
value. If the unmarshaling fails, f will not be called and the unmarshal error
will be written as a JSON response.

If an error is returned from f, it is passed through the error mapper before
writing as a JSON response.

In the third form, when no error is returned, the result is written as a JSON
response with status http.StatusOK.

Handle will panic if the provided function is not in one of the above forms.

#### func (ErrorMapper) HandleErrors

func (e ErrorMapper) HandleErrors(handle ErrorHandler) httprouter.Handle
HandleErrors returns a handler that passes any non-nil error returned by handle
through the error mapper and writes it as a JSON response.

#### func (ErrorMapper) HandleJSON

func (e ErrorMapper) HandleJSON(handle JSONHandler) httprouter.Handle
HandleJSON returns a handler that writes the return value of handle as a JSON
response. If handle returns an error, it is passed through the error mapper.

#### func (ErrorMapper) WriteError

func (e ErrorMapper) WriteError(w http.ResponseWriter, err error)
WriteError writes an error to a ResponseWriter and sets the HTTP status code.

#### type JSONHandler

type JSONHandler func(http.Header, Params) (interface{}, error)

JSONHandler is like httprouter.Handle except that it returns a body (to be
converted to JSON) and an error. The Header parameter can be used to set custom
headers on the response.

#### type Params

type Params struct {
	PathVar httprouter.Params

Params holds request parameters that can be unmarshaled into a struct.


Last updated on 18 Oct 2017

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc