jsonapi

README

jsonapi

An extensible JSON API implementation for Go.

Package jsonapi provides structures and methods to implement JSON API compatible APIs. Most methods are tailored to be used together with the echo framework, yet all of them also have a native counterpart in the compat sub package that allows implementing APIs using the standard HTTP library.

License

The MIT License (MIT)

Copyright (c) 2016 Joël Gähwiler

Documentation

Overview

Package jsonapi provides structures and methods to implement JSON API compatible APIs. Most methods are tailored to be used together with the echo framework, yet all of them also have a native counterpart in the compat sub package that allows implementing APIs using the standard HTTP library.

Index

• Constants
• func MapToStruct(m interface{}, s interface{}, tagName ...string) error
• func WriteError(res engine.Response, err error) error
• func WriteErrorList(res engine.Response, errors ...*Error) error
• func WriteResource(res engine.Response, status int, resource *Resource, links *DocumentLinks, ...) error
• func WriteResources(res engine.Response, status int, resources []*Resource, links *DocumentLinks, ...) error
• func WriteResponse(res engine.Response, status int, doc *Document) error
• type Document
  • func ParseBody(r io.Reader) (*Document, error)
• type DocumentLinks
• type Error
  • func BadRequest(detail string) *Error
  • func BadRequestParam(detail, param string) *Error
  • func ErrorFromStatus(status int, detail string) *Error
  • func InternalServerError(detail string) *Error
  • func NotFound(detail string) *Error
  • func (e *Error) Error() string
• type ErrorLinks
• type ErrorSource
• type HybridResource
  • func (r *HybridResource) MarshalJSON() ([]byte, error)
  • func (r *HybridResource) UnmarshalJSON(doc []byte) error
• type Intent
  • func (i Intent) DocumentExpected() bool
• type Map
• type Request
  • func ParseRequest(req engine.Request, prefix string) (*Request, error)
  • func (r *Request) Self() string
• type Resource

Constants

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

MediaType is the official JSON API media type that should be used by all requests and responses.

Functions

func MapToStruct

func MapToStruct(m interface{}, s interface{}, tagName ...string) error

MapToStruct wraps the mapstructure package to provide a simple way to assign map values to a struct. The optional parameter tag name defaults to "json".

func WriteError

func WriteError(res engine.Response, err error) error

WriteError will write the passed error to the response writer.

Note: If the supplied error is not an Error a new InternalServerError is used instead. Does the passed Error have an invalid or zero status code it will be corrected to the Internal Server Error status code.

func WriteErrorList

func WriteErrorList(res engine.Response, errors ...*Error) error

WriteErrorList will write the passed errors to the the response writer. The method will calculate a common status code for all the errors.

Does a passed Error have an invalid or zero status code it will be corrected to the Internal Server Error status code.

func WriteResource

func WriteResource(res engine.Response, status int, resource *Resource, links *DocumentLinks, included ...*Resource) error

WriteResource will wrap the passed resource, links and included resources in a document and write it to the passed response writer.

func WriteResources

func WriteResources(res engine.Response, status int, resources []*Resource, links *DocumentLinks, included ...*Resource) error

WriteResources will wrap the passed resources, links and included resources in a document and write it to the passed response writer.

func WriteResponse

func WriteResponse(res engine.Response, status int, doc *Document) error

WriteResponse will write the the status and supplied document to the passed response writer.

Types

type Document

type Document struct {
	// The documents's primary data in the form of a single resource or a list
	// of resources.
	Data *HybridResource `json:"data,omitempty"`

	// A list of resources that are related to the primary data and/or other
	// included resources.
	Included []*Resource `json:"included,omitempty"`

	// A set of links related to the primary data.
	Links *DocumentLinks `json:"links,omitempty"`

	// A list of errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty"`

	// Non-standard meta-information about the document.
	Meta Map `json:"meta,omitempty"`
}

A Document is the root structure of every JSON API response. It is also used to include relationships.

See: http://jsonapi.org/format/#document-top-level.

func ParseBody

func ParseBody(r io.Reader) (*Document, error)

ParseBody will decode a JSON API document from the passed request body reader.

type DocumentLinks

type DocumentLinks struct {
	Self     string `json:"self,omitempty"`
	Related  string `json:"related,omitempty"`
	First    string `json:"first,omitempty"`
	Previous string `json:"prev,omitempty"`
	Next     string `json:"next,omitempty"`
	Last     string `json:"last,omitempty"`
}

DocumentLinks are a set of links related to a documents primary data.

See: http://jsonapi.org/format/#document-links.

type Error

type Error struct {
	// A unique identifier for this particular occurrence of the problem.
	ID string `json:"id,omitempty"`

	// Continuing links to other resources.
	Links *ErrorLinks `json:"links,omitempty"`

	// The HTTP status code applicable to this problem.
	Status int `json:"status,string,omitempty"`

	// An application-specific error code.
	Code string `json:"code,omitempty"`

	// A short, human-readable summary of the problem.
	Title string `json:"title,omitempty"`

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

	// A parameter or pointer reference to the source of the error.
	Source *ErrorSource `json:"source,omitempty"`

	// Non-standard meta-information about the error.
	Meta Map `json:"meta,omitempty"`
}

Error objects provide additional information about problems encountered while performing an operation.

See: http://jsonapi.org/format/#errors.

func BadRequest

func BadRequest(detail string) *Error

BadRequest returns a new bad request error.

func BadRequestParam

func BadRequestParam(detail, param string) *Error

BadRequestParam returns a new bad request error with a parameter source.

func ErrorFromStatus

func ErrorFromStatus(status int, detail string) *Error

ErrorFromStatus will return an error that has been derived from the passed status code.

Note: If the passed status code is not a valid HTTP status code, an Internal Server Error status code will be used instead.

func InternalServerError

func InternalServerError(detail string) *Error

InternalServerError returns na new internal server error.

func NotFound

func NotFound(detail string) *Error

NotFound returns a new not found error.

func (*Error) Error

func (e *Error) Error() string

Error returns a string representation of the error for logging purposes.

type ErrorLinks

type ErrorLinks struct {
	// A link that leads to further details about this particular occurrence of
	// the problem.
	About string `json:"about"`
}

ErrorLinks contains continuing links to other resources.

See: http://jsonapi.org/format/#errors.

type ErrorSource

type ErrorSource struct {
	// A string indicating which URI query parameter caused the error.
	Parameter string `json:"parameter,omitempty"`

	// A JSON Pointer to the associated entity in the request document.
	Pointer string `json:"pointer,omitempty"`
}

ErrorSource contains a parameter or pointer reference to the source of the error.

See: http://jsonapi.org/format/#errors.

type HybridResource

type HybridResource struct {
	// A single Resource.
	One *Resource

	// A list of Resources.
	Many []*Resource
}

HybridResource is a transparent type that enables concrete marshalling and unmarshalling of a single resource value or a list of resources.

func (*HybridResource) MarshalJSON

func (r *HybridResource) MarshalJSON() ([]byte, error)

MarshalJSON will either encode a list or a single object.

func (*HybridResource) UnmarshalJSON

func (r *HybridResource) UnmarshalJSON(doc []byte) error

UnmarshalJSON detects if the passed JSON is a single object or a list.

type Intent

type Intent int

An Intent represents a valid combination of a request method and a URL pattern.

const (

	// ListResources is a variation of the following request:
	// GET /posts
	ListResources Intent

	// FindResource is a variation of the following request:
	// GET /posts/1
	FindResource

	// CreateResource is a variation of the following request:
	// POST /posts
	CreateResource

	// UpdateResource is a variation of the following request:
	// PATCH /posts/1
	UpdateResource

	// DeleteResource is a variation of the following request:
	// DELETE /posts/1
	DeleteResource

	// GetRelatedResources is a variation of the following requests:
	// GET /posts/1/author
	// GET /posts/1/comments
	GetRelatedResources

	// GetRelationship is a variation of the following requests:
	// GET /posts/1/relationships/author
	// GET /posts/1/relationships/comments
	GetRelationship

	// SetRelationship is a variation of the following requests:
	// PATCH /posts/1/relationships/author.
	// PATCH /posts/1/relationships/comments.
	SetRelationship

	// AppendToRelationship is a variation of the following request:
	// POST /posts/1/relationships/comments
	AppendToRelationship

	// RemoveFromRelationship is a variation of the following request:
	// DELETE /posts/1/relationships/comments
	RemoveFromRelationship
)

func (Intent) DocumentExpected

func (i Intent) DocumentExpected() bool

DocumentExpected returns whether the intent is expected to come with a JSON API document.

type Map

type Map map[string]interface{}

Map is a general purpose map of string keys and arbitrary values.

type Request

type Request struct {
	// The parsed JSON API intent of the request.
	Intent Intent

	// The fragments parsed from the URL of the request.
	Prefix          string
	ResourceType    string
	ResourceID      string
	RelatedResource string
	Relationship    string

	// The requested resources to be included in the response.
	Include []string

	// The pagination details of the request. Zero values mean no pagination
	// details have been provided.
	PageNumber int
	PageSize   int

	// The sorting that has been requested.
	Sorting []string

	// The sparse fieldsets that have been requested.
	Fields map[string][]string

	// The filtering that has been requested.
	Filters map[string][]string
}

A Request contains all JSON API related information parsed from a low level request.

func ParseRequest

func ParseRequest(req engine.Request, prefix string) (*Request, error)

ParseRequest will parse the passed request and return a new Request with the parsed data. It will return an error if the content type, request method or url is invalid.

Note: The returned error can directly be written using WriteError.

func (*Request) Self

func (r *Request) Self() string

Self will generate the "self" URL for this request.

type Resource

type Resource struct {
	// The mandatory type of the resource.
	Type string `json:"type"`

	// The mandatory id of the resource.
	//
	// Exception: The id is not required when the resource object
	// originates at the client and represents a new resource to be created on
	// the server.
	ID string `json:"id,omitempty"`

	// An attributes object representing some of the resource's data.
	//
	// This field will contain a Map after parsing a request body and might be
	// directly set to JSON compatible struct for writing responses.
	Attributes interface{} `json:"attributes,omitempty"`

	// A relationships object describing relationships between the resource and
	// other JSON API resources.
	Relationships map[string]*Document `json:"relationships,omitempty"`

	// Non-standard meta-information about the resource.
	Meta Map `json:"meta,omitempty"`
}

A Resource is carried by a document and provides the basic structure for JSON API resource objects and resource identifier objects.

See: http://jsonapi.org/format/#document-resource-objects and http://jsonapi.org/format/#document-resource-identifier-objects.