jsonapi

package
v0.0.0-...-0e769ad Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 18, 2025 License: AGPL-3.0 Imports: 10 Imported by: 32

Documentation

Overview

Package jsonapi is for using the JSON-API format: parsing, serialization, checking the content-type, etc.

Index

Constants

View Source 
const ContentType = "application/vnd.api+json"

ContentType is the official mime-type for JSON-API

Variables

This section is empty.

Functions

func BindRelations 

func BindRelations(req *http.Request) ([]couchdb.DocReference, error)

BindRelations extracts a Relationships request ( a list of ResourceIdentifier)

func Data 

func Data(c echo.Context, statusCode int, o Object, links *LinksList) error

Data can be called to send an answer with a JSON-API document containing a single object as data

func DataError 

func DataError(c echo.Context, err *Error) error

DataError can be called to send an error answer with a JSON-API document containing a single value error.

func DataErrorList 

func DataErrorList(c echo.Context, errs ...*Error) error

DataErrorList can be called to send an error answer with a JSON-API document containing multiple errors.

func DataList 

func DataList(c echo.Context, statusCode int, objs []Object, links *LinksList) error

DataList can be called to send an multiple-value answer with a JSON-API document contains multiple objects.

func DataListWithMeta 

func DataListWithMeta(c echo.Context, statusCode int, meta Meta, objs []Object, links *LinksList) error

DataListWithMeta can be called to send a list of Objects with meta like a count, useful to indicate total number of results with pagination.

func DataRelations 

func DataRelations(c echo.Context, statusCode int, refs []couchdb.DocReference, meta *Meta, links *LinksList, included []Object) error

DataRelations can be called to send a Relations page, a list of ResourceIdentifier

func ExtractPaginationCursor 

func ExtractPaginationCursor(c echo.Context, defaultLimit, maxLimit int) (couchdb.Cursor, error)

ExtractPaginationCursor creates a Cursor from context Query.

func MarshalObject 

func MarshalObject(o Object) (json.RawMessage, error)

MarshalObject serializes an Object to JSON. It returns a json.RawMessage that can be used a in Document.

func PaginationCursorToParams 

func PaginationCursorToParams(cursor couchdb.Cursor) (url.Values, error)

PaginationCursorToParams transforms a Cursor into url.Values the url.Values contains only keys page[limit] & page[cursor] if the cursor is Done, the values will be empty.

func WriteData 

func WriteData(w io.Writer, o Object, links *LinksList) error

WriteData can be called to write an answer with a JSON-API document containing a single object as data into an io.Writer.

Types

type Document 

type Document struct {
	Data     *json.RawMessage `json:"data,omitempty"`
	Errors   ErrorList        `json:"errors,omitempty"`
	Links    *LinksList       `json:"links,omitempty"`
	Meta     *Meta            `json:"meta,omitempty"`
	Included []interface{}    `json:"included,omitempty"`
}

Document is JSON-API document, identified by the mediatype application/vnd.api+json See http://jsonapi.org/format/#document-structure

type Error 

type Error struct {
	Status int         `json:"status,string"`
	Title  string      `json:"title"`
	Code   string      `json:"code,omitempty"`
	Detail string      `json:"detail,omitempty"`
	Source SourceError `json:"source,omitempty"`
	Links  *LinksList  `json:"links,omitempty"`
}

Error objects provide additional information about problems encountered while performing an operation. See http://jsonapi.org/format/#error-objects

func BadGateway 

func BadGateway(err error) *Error

BadGateway returns a 502 formatted error

func BadJSON 

func BadJSON() *Error

BadJSON returns a 400 formatted error meaning the json input is malformed.

func BadRequest 

func BadRequest(err error) *Error

BadRequest returns a 400 formatted error

func Conflict 

func Conflict(err error) *Error

Conflict returns a 409 formatted error representing a conflict

func Errorf 

func Errorf(status int, format string, args ...interface{}) *Error

Errorf creates a new generic Error with detail build as Sprintf

func Forbidden 

func Forbidden(err error) *Error

Forbidden returns a 403 Forbidden error formatted when an action is fobidden.

func InternalServerError 

func InternalServerError(err error) *Error

InternalServerError returns a 500 formatted error

func InvalidAttribute 

func InvalidAttribute(attribute string, err error) *Error

InvalidAttribute returns a 422 formatted error when an attribute is invalid

func InvalidParameter 

func InvalidParameter(parameter string, err error) *Error

InvalidParameter returns a 422 formatted error when an HTTP or Query-String parameter is invalid

func MethodNotAllowed 

func MethodNotAllowed(method string) *Error

MethodNotAllowed returns a 405 formatted error

func NewError 

func NewError(status int, detail string) *Error

NewError creates a new generic Error

func NotFound 

func NotFound(err error) *Error

NotFound returns a 404 formatted error

func PreconditionFailed 

func PreconditionFailed(parameter string, err error) *Error

PreconditionFailed returns a 412 formatted error when an expectation from an HTTP header is not matched

func Unauthorized 

func Unauthorized(err error) *Error

Unauthorized returns a 401 formatted error

func (*Error) Error 

func (e *Error) Error() string

type ErrorList 

type ErrorList []*Error

ErrorList is just an array of error objects 

type LinksList struct {
	Self    string `json:"self,omitempty"`
	Related string `json:"related,omitempty"`
	Prev    string `json:"prev,omitempty"`
	Next    string `json:"next,omitempty"`
	Icon    string `json:"icon,omitempty"`
	Perms   string `json:"permissions,omitempty"`
	Webhook string `json:"webhook,omitempty"`
	// Thumbnails
	Tiny   string `json:"tiny,omitempty"`
	Small  string `json:"small,omitempty"`
	Medium string `json:"medium,omitempty"`
	Large  string `json:"large,omitempty"`
	// Preview for PDF
	Preview string `json:"preview,omitempty"`
}

LinksList is the common links used in JSON-API for the top-level or a resource object See http://jsonapi.org/format/#document-links

type Meta 

type Meta struct {
	Rev            string                  `json:"rev,omitempty"`
	Warning        string                  `json:"warning,omitempty"`
	Count          *int                    `json:"count,omitempty"`
	ExecutionStats *couchdb.ExecutionStats `json:"execution_stats,omitempty"`
}

Meta is a container for the couchdb revision and the total number of items, in JSON-API land

type Object 

type Object interface {
	couchdb.Doc
	Links() *LinksList
	Relationships() RelationshipMap
	Included() []Object
}

Object is an interface to serialize something to a JSON-API Object

type ObjectMarshalling 

type ObjectMarshalling struct {
	Type          string           `json:"type"`
	ID            string           `json:"id"`
	Attributes    *json.RawMessage `json:"attributes"`
	Meta          Meta             `json:"meta"`
	Links         *LinksList       `json:"links,omitempty"`
	Relationships RelationshipMap  `json:"relationships,omitempty"`
}

ObjectMarshalling is a JSON-API object See http://jsonapi.org/format/#document-resource-objects

func Bind 

func Bind(body io.Reader, attrs interface{}) (*ObjectMarshalling, error)

Bind is used to unmarshal an input JSONApi document. It binds an incoming request to a attribute type.

func BindCompound 

func BindCompound(body io.Reader) ([]*ObjectMarshalling, error)

BindCompound is used to unmarshal an compound input JSONApi document.

func (*ObjectMarshalling) GetRelationship 

func (o *ObjectMarshalling) GetRelationship(name string) (*Relationship, bool)

GetRelationship returns the relationship with the given name from the relationships map.

type Relationship 

type Relationship struct {
	Links *LinksList  `json:"links,omitempty"`
	Meta  *Meta       `json:"meta,omitempty"`
	Data  interface{} `json:"data"`
}

Relationship is a resource linkage, as described in JSON-API See http://jsonapi.org/format/#document-resource-object-relationships

Data can be a single ResourceIdentifier for to-one relationships, or an array of them for to-many relationships.

func (*Relationship) ResourceIdentifier 

func (r *Relationship) ResourceIdentifier() (*couchdb.DocReference, bool)

ResourceIdentifier returns the resource identifier of the relationship.

type RelationshipMap 

type RelationshipMap map[string]Relationship

RelationshipMap is a map of relationships See http://jsonapi.org/format/#document-resource-object-relationships

type SourceError 

type SourceError struct {
	Pointer   string `json:"pointer,omitempty"`
	Parameter string `json:"parameter,omitempty"`
}

SourceError contains references to the source of the error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.