rfc9457

README

rfc9457 provides an implementation of the RFC "Problem Details for HTTP APIs" in Go

RFC 9457

---

Usage

See examples/main.go for information in using the library.

Suggested Implementation

package main

import (
	"net/http"

	"alpineworks.io/rfc9457"
)

func main() {
	http.Handle("/test", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
		rfc9457.NewRFC9457(
			rfc9457.WithStatus(http.StatusTeapot),
			rfc9457.WithDetail("I'm a teapot"),
			rfc9457.WithTitle("Test endpoint hit - I'm a teapot"),
			rfc9457.WithInstance("/test"),
		).ServeHTTP(w, req)
	}))

	http.ListenAndServe(":8080", nil)
}

Output

curl localhost:8080/test

{
	"detail": "I'm a teapot",
	"instance": "/test",
	"status": 418,
	"title": "Test endpoint hit - I'm a teapot",
	"type": "about:blank"
}

Documentation

Index

• Constants
• type Extension
  • func NewExtension(key string, value any) Extension
• type RFC9457
  • func FromJSON(jsonString string) (*RFC9457, error)
  • func NewRFC9457(options ...RFC9457Option) *RFC9457
  • func (r *RFC9457) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *RFC9457) ToJSON() (string, error)
  • func (r *RFC9457) Write() http.HandlerFunc
• type RFC9457Error
  • func (e RFC9457Error) Error() string
• type RFC9457Option
  • func WithDetail(d string) RFC9457Option
  • func WithExtensions(e ...Extension) RFC9457Option
  • func WithInstance(i string) RFC9457Option
  • func WithStatus(i int) RFC9457Option
  • func WithTitle(t string) RFC9457Option
  • func WithType(t string) RFC9457Option

Constants

const (
	ProblemContentType string = "application/problem+json"
)

Types

type Extension

type Extension struct {
	Key   string
	Value any
}

func NewExtension

func NewExtension(key string, value any) Extension

type RFC9457

type RFC9457 struct {
	// The "type" member is a JSON string containing a URI reference [URI] that identifies the problem type.
	// Consumers MUST use the "type" URI (after resolution, if necessary) as the problem type's primary identifier.
	// When this member is not present, its value is assumed to be "about:blank".
	//
	// https://datatracker.ietf.org/doc/html/rfc9457#name-type
	Type string `json:"type" mapstructure:"type"`

	// The "status" member is a JSON number indicating the HTTP status code generated by the origin server for this occurrence of the problem.
	// The "status" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer.
	//
	// https://datatracker.ietf.org/doc/html/rfc9457#name-status
	Status int `json:"status,omitempty" mapstructure:"status,omitempty"`

	// The "title" member is a JSON string containing a short, human-readable summary of the problem type.
	// It SHOULD NOT change from occurrence to occurrence of the problem, except for localization.
	// The "title" string is advisory and is included only for users who are unaware of and cannot discover the semantics of the type URI.
	//
	// https://datatracker.ietf.org/doc/html/rfc9457#name-title
	Title string `json:"title" mapstructure:"title"`

	// The "detail" member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.
	// The "detail" string, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.
	//
	// https://datatracker.ietf.org/doc/html/rfc9457#name-detail
	Detail string `json:"detail,omitempty" mapstructure:"detail,omitempty"`

	// The "instance" member is a JSON string containing a URI reference that identifies the specific occurrence of the problem.
	//
	// https://datatracker.ietf.org/doc/html/rfc9457#name-instance
	Instance string `json:"instance" mapstructure:"instance"`

	// Problem type definitions MAY extend the problem details object with additional members that are specific to that problem type.
	//
	// https://datatracker.ietf.org/doc/html/rfc9457#name-extension-members
	Extensions map[string]any `json:"-" mapstructure:"extensions,remain"`
}

func FromJSON

func FromJSON(jsonString string) (*RFC9457, error)

func NewRFC9457

func NewRFC9457(options ...RFC9457Option) *RFC9457

func (*RFC9457) ServeHTTP

func (r *RFC9457) ServeHTTP(w http.ResponseWriter, req *http.Request)

func (*RFC9457) ToJSON

func (r *RFC9457) ToJSON() (string, error)

func (*RFC9457) Write

func (r *RFC9457) Write() http.HandlerFunc

type RFC9457Error

type RFC9457Error int

const (
	ErrUnableToMarshalJSON RFC9457Error = iota
	ErrUnableToUnmarshalJSON
	ErrUnableToTranslateToIntermediateMap
	ErrUnableToTranslateToRFC9457
)

func (RFC9457Error) Error

func (e RFC9457Error) Error() string

type RFC9457Option

type RFC9457Option func(*RFC9457)

func WithDetail

func WithDetail(d string) RFC9457Option

func WithExtensions

func WithExtensions(e ...Extension) RFC9457Option

func WithInstance

func WithInstance(i string) RFC9457Option

func WithStatus

func WithStatus(i int) RFC9457Option

func WithTitle

func WithTitle(t string) RFC9457Option

func WithType

func WithType(t string) RFC9457Option