jsonapi

package module
Version: v1.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2019 License: MIT Imports: 8 Imported by: 0

README

jsonapi

Build Status Coverage Status GoDoc Release Go Report Card

A fundamental and extendable JSON API library for Go.

Package jsonapi provides structures and functions to implement JSON API compatible APIs. The library can be used with any framework and is built on top of the standard Go http library.

Extensions

Custom Actions

The package supports the non-standard but widely adopted "custom actions" extension to support the following patterns:

GET /posts/highlighted
DELETE /posts/cache
POST /posts/1/publish
DELETE /posts/1/history

Examples

The server example implements a basic API server using the standard HTTP package.

Installation

Get the package using the go tool:

$ go get -u github.com/256dpi/jsonapi

License

The MIT License (MIT)

Copyright (c) 2016 Joël Gähwiler

Documentation

Overview

Package jsonapi provides structures and functions to implement JSON API compatible APIs. The library can be used with any framework and is built on top of the standard Go http library.

Index

Constants

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

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

Variables

This section is empty.

Functions

func WriteError

func WriteError(w http.ResponseWriter, 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(w http.ResponseWriter, errors ...*Error) error

WriteErrorList will write the passed errors to the the response writer. The function 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(w http.ResponseWriter, 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(w http.ResponseWriter, 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(w http.ResponseWriter, 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.
	//
	// Note: Numbers are left as strings to avoid issues with mismatching types
	// when they are later assigned to a struct.
	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 ParseDocument added in v0.2.0

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

ParseDocument will decode a JSON API document from the passed reader.

Note: If the read document contains errors the first Error will be returned as an error.

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.
	//
	// Note: Numbers are left as strings to avoid issues with mismatching types
	// when they are later assigned to a struct.
	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 BadRequestPointer added in v0.2.1

func BadRequestPointer(detail, pointer string) *Error

BadRequestPointer returns a new bad request error with a pointer 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 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

	// CollectionAction is a variation of the following requests:
	// GET /posts/top-titles
	// POST /posts/lock
	// PATCH /posts/settings
	// DELETE /posts/cache
	CollectionAction

	// ResourceAction is a variation of the following requests:
	// GET /posts/1/meta-data
	// POST /posts/1/publish
	// PATCH /posts/1/settings
	// DELETE /posts/1/history
	ResourceAction
)

func (Intent) DocumentExpected

func (i Intent) DocumentExpected() bool

DocumentExpected returns whether a request using this intent is expected to include a JSON API document.

Note: A response from an API may always include a document that at least contains one ore more errors.

func (Intent) RequestMethod added in v0.2.0

func (i Intent) RequestMethod() string

RequestMethod returns the matching HTTP request method for an Intent.

type Map

type Map map[string]interface{}

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

Note: All methods in this package will leave numbers as strings to avoid issues with mismatching types when they are later assigned to a struct.

func StructToMap added in v0.2.1

func StructToMap(source interface{}, fields []string) (Map, error)

StructToMap will assign the fields of the source struct to a new map and additionally filter the map to only include the fields specified.

Note: The "json" tag will be respected to write proper field names. No filtering will be applied if fields is nil.

Note: Numbers are left as strings to avoid issues with mismatching types when they are later assigned to a struct again.

Warning: The function does actually convert the struct to json and then convert that json to a map. High performance applications might want to use a custom implementation that is much faster.

func (Map) Assign added in v0.3.0

func (m Map) Assign(target interface{}) error

Assign will assign the values in the map to the target struct.

Note: The "json" tag will be respected to match field names.

Warning: The function does actually convert the map to json and then assign that json to the struct. High performance applications might want to use a custom implementation that is much faster.

type Parser added in v1.1.0

type Parser struct {
	// Prefix is the expected prefix of the endpoint.
	Prefix string

	// A list of valid collection actions and the allowed methods.
	//
	// Note: Make sure the actions do not conflict with the resource id format.
	CollectionActions map[string][]string

	// A list of valid resource actions and the allowed methods.
	//
	// Note: Make sure the actions do not contain "relationships" or use
	// related resource types.
	ResourceActions map[string][]string
}

A Parser is used to parse incoming requests.

func (*Parser) ParseRequest added in v1.1.0

func (p *Parser) ParseRequest(r *http.Request) (*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. Any returned error can directly be written using WriteError.

type Request

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

	// The prefix of the endpoint e.g. "api". It should not contain any prefix
	// or suffix slashes.
	Prefix string

	// The fragments parsed from the URL of the request. The fragments should not
	// contain any prefix or suffix slashes.
	ResourceType     string
	ResourceID       string
	RelatedResource  string
	Relationship     string
	CollectionAction string
	ResourceAction   string

	// The requested resources to be included in the response. This is read
	// from the "include" query parameter.
	Include []string

	// The pagination details of the request. Zero values mean no pagination
	// details have been provided. These values are read from the "page[number]",
	// "page[size]", "page[offset]" and "page[limit]" query parameters. These
	// parameters do not belong to the standard, but are recommended.
	PageNumber uint64
	PageSize   uint64
	PageOffset uint64
	PageLimit  uint64

	// The sorting that has been requested. This is read from the "sort" query
	// parameter.
	Sorting []string

	// The sparse fields that have been requested. This is read from the "fields"
	// query parameter.
	Fields map[string][]string

	// The filtering that has been requested. This is read from the "filter"
	// query parameter. This parameter does not belong to the standard, but is
	// recommended.
	Filters map[string][]string

	// Original references the original request.
	Original *http.Request
}

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

func ParseRequest

func ParseRequest(r *http.Request, prefix string) (*Request, error)

ParseRequest is a short-hand for Parser.ParseRequest and will be removed in future releases.

func (*Request) Base added in v0.6.4

func (r *Request) Base() string

Base will generate the base URL for this request, which includes the type and id if present.

func (*Request) Self

func (r *Request) Self() string

Self will generate the "self" URL for this request, which includes all path elements if available.

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 map representing some of the resource's data.
	//
	// Note: Numbers are left as strings to avoid issues with mismatching types
	// when they are later assigned to a struct.
	Attributes Map `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.
	//
	// Note: Numbers are left as strings to avoid issues with mismatching types
	// when they are later assigned to a struct.
	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.

Directories

Path Synopsis
This example implements a basic API server using the standard HTTP package.
This example implements a basic API server using the standard HTTP package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL