problem

Documentation

Overview

Package problem implements the RFC7807 Details for HTTP APIs.

Further reading https://tools.ietf.org/html/rfc7807

Index

• Constants
• type Detail
  • func MustNewDetail(title string, opts ...Option) *Detail
  • func NewDetail(title string, opts ...Option) (*Detail, error)
  • func (v Detail) MarshalEasyJSON(w *jwriter.Writer)
  • func (v Detail) MarshalJSON() ([]byte, error)
  • func (d *Detail) Options(opts ...Option) error
  • func (v *Detail) UnmarshalEasyJSON(l *jlexer.Lexer)
  • func (v *Detail) UnmarshalJSON(data []byte) error
  • func (d *Detail) Validate() error
• type Option
  • func WithCause(title string, opts ...Option) Option
  • func WithExtensionInt(key string, value int) Option
  • func WithExtensionMapString(m map[string]string) Option
  • func WithExtensionMapStringSlice(m map[string][]string) Option
  • func WithExtensionString(keyValues ...string) Option
  • func WithExtensionUint(key string, value uint64) Option

Constants

const (
	// MediaType specifies the default media type for a Detail response
	MediaType = "application/problem+json"

	// MediaTypeXML specifies the XML variant on the Detail Media type
	MediaTypeXML = "application/problem+xml"

	// DefaultURL is the default url to use for problem types
	DefaultURL = "about:blank"
)

Types

type Detail

type Detail struct {
	// Type - A URI reference [RFC3986] that identifies the problem type.  This
	// specification encourages that, when dereferenced, it provide
	// human-readable documentation for the problem type (e.g., using HTML
	// [W3C.REC-html5-20141028]).  When this member is not present, its value is
	// assumed to be "about:blank".
	Type string `json:"type" xml:"type"`

	// Title - A short, human-readable summary of the problem type.  It SHOULD
	// NOT change from occurrence to occurrence of the problem, except for
	// purposes of localization.
	Title string `json:"title" xml:"title"`

	// Status specifies the HTTP status code generated by the origin server for
	// this occurrence of the problem.
	Status int `json:"status,omitempty" xml:"status,omitempty"`

	// Detail states a human-readable explanation specific to this occurrence of the
	// problem.
	Detail string `json:"detail,omitempty" xml:"detail,omitempty"`

	// Instance states an URI that identifies the specific occurrence of the
	// problem. This URI may or may not yield further information if
	// dereferenced.
	Instance string `json:"instance,omitempty" xml:"instance,omitempty"`

	// Cause can reference to the underlying real cause of a problem detail.
	Cause *Detail `json:"cause,omitempty" xml:"cause,omitempty"`

	// Extension defines additional custom key/value pairs in a balanced slice.
	// i=key and i+1=value. They will be transformed into a key/value JSON type.
	Extension []string
}

Detail is a default problem implementation. Problem details are not a debugging tool for the underlying implementation; rather, they are a way to expose greater detail about the HTTP interface itself. Designers of new problem types need to carefully consider the Security Considerations, in particular, the risk of exposing attack vectors by exposing implementation internals through error messages.

func MustNewDetail

func MustNewDetail(title string, opts ...Option) *Detail

MustNewDetail same as NewDetail but panics on error.

func NewDetail

func NewDetail(title string, opts ...Option) (*Detail, error)

NewDetail returns a new instance of a Detail problem.

func (Detail) MarshalEasyJSON

func (v Detail) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Detail) MarshalJSON

func (v Detail) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Detail) Options

func (d *Detail) Options(opts ...Option) error

Options applies options to the details object.

func (*Detail) UnmarshalEasyJSON

func (v *Detail) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Detail) UnmarshalJSON

func (v *Detail) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

func (*Detail) Validate

func (d *Detail) Validate() error

Validate returns an error if the title is empty, or type is not an URI or Extension field is imbalanced.

type Option

type Option func(*Detail) error

Option applies an option to the Detail object

func WithCause

func WithCause(title string, opts ...Option) Option

WithCause adds a detail as a new cause.

func WithExtensionInt

func WithExtensionInt(key string, value int) Option

WithExtensionInt adds an int to the Extension field.

func WithExtensionMapString

func WithExtensionMapString(m map[string]string) Option

WithExtensionMapString adds a string only map to the Extension field.

func WithExtensionMapStringSlice

func WithExtensionMapStringSlice(m map[string][]string) Option

WithExtensionMapStringSlice adds a special map to the Extension field. This kind of map gets implemented by url.Values, http.Header, mail.Header and textproto.MIMEHeader.

func WithExtensionString

func WithExtensionString(keyValues ...string) Option

WithExtensionString adds one or more key/value pairs to the Extension field.

func WithExtensionUint

func WithExtensionUint(key string, value uint64) Option

WithExtensionUint adds an uint to the Extension field.