jsonapi

README

JSON:API implementation for Go

Why another JSON:API serialization library?

There are a few other JSONAPI libraries for Go. Some are rather good but not actively maintaned, other feel to pull in way more than they should. The goal of this one is to strictly follow the JSON:API specification and to clutter your codebase with as little implementation details as possible.

Target constraints

• Do not require implementation of any specific interface outside of the standard library
• Do not introduce vendor struct tags beyond what's absolutely necessary. Prioritize using json tag instead
• Full support for JSON:API 1.1
• Zero dependencies
• Minimize runtime overhead

Explicitly out of scope

Anything related to the underlying API implementation is out of scope. This includes:

• Filtering
• Sorting
• Pagination
• Support for "schema-less" structures (though you can use map[string]interface{} for that still)

Leaving it entirely up to the user how to structure their API.

However, we can provide some helper methods to make it easier to pair the implementations up.

Documentation

Index

• Constants
• func Marshal(in interface{}) ([]byte, error)
• func MarshalErrors(errs []*JSONAPIError) ([]byte, error)
• func MarshalMany(in interface{}) ([]byte, error)
• func MarshalOne(in interface{}) ([]byte, error)
• func MixInMeta(source []byte, meta map[string]interface{}) ([]byte, error)
• func Unmarshal(data []byte, model interface{}) error
• func UnmarshalManyAsType(payload []byte, model reflect.Type) ([]interface{}, error)
• func UnmarshalOneAsType(payload []byte, model reflect.Type) (interface{}, error)
• type ErrorsPayload
• type JSONAPIError
  • func (e *JSONAPIError) Error() string

Constants

const MediaType = "application/vnd.api+json"

Functions

func Marshal

func Marshal(in interface{}) ([]byte, error)

func MarshalErrors

func MarshalErrors(errs []*JSONAPIError) ([]byte, error)

func MarshalMany

func MarshalMany(in interface{}) ([]byte, error)

func MarshalOne

func MarshalOne(in interface{}) ([]byte, error)

func MixInMeta

func MixInMeta(source []byte, meta map[string]interface{}) ([]byte, error)

func Unmarshal

func Unmarshal(data []byte, model interface{}) error

func UnmarshalManyAsType

func UnmarshalManyAsType(payload []byte, model reflect.Type) ([]interface{}, error)

func UnmarshalOneAsType

func UnmarshalOneAsType(payload []byte, model reflect.Type) (interface{}, error)

Types

type ErrorsPayload

type ErrorsPayload struct {
	Errors []*JSONAPIError `json:"errors"`
}

type JSONAPIError

type JSONAPIError struct {
	//id: a unique identifier for this particular occurrence of the problem.
	ID string `json:"id"`
	//status: the HTTP status code applicable to this problem, expressed as a string value. This SHOULD be provided.
	Status string `json:"status"`
	//code: an application-specific error code, expressed as a string value.
	Code string `json:"code,omitempty"`
	//title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
	Title string `json:"title"`
	//detail: a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
	Detail string `json:"detail"`
	/*
		source: an object containing references to the primary source of the error. It SHOULD include one of the following members or be omitted:

		    pointer: a JSON Pointer [RFC6901] to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
		    parameter: a string indicating which URI query parameter caused the error.
		    header: a string indicating the name of a single request header which caused the error.
	*/
	Source map[string]interface{} `json:"source,omitempty"`
	//meta: a meta object containing non-standard meta-information about the error.
	Meta map[string]interface{} `json:"meta,omitempty"`
	//links: a links object that MAY contain the following members:
	//
	//    about: a link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
	//    type: a link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
	Links map[string]interface{} `json:"links,omitempty"`
}

func (*JSONAPIError) Error

func (e *JSONAPIError) Error() string