jsonapi

README

jsonapi

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.

Examples

The following examples show the usage of this package:

• The server example implements a basic API server using the standard HTTP package.
• The client example uses the client to query the example API.

Installation

Get the package using the go tool:

$ go get -u github.com/gonfire/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
• func WriteError(w http.ResponseWriter, err error) error
• func WriteErrorList(w http.ResponseWriter, errors ...*Error) error
• func WriteResource(w http.ResponseWriter, status int, resource *Resource, links *DocumentLinks, ...) error
• func WriteResources(w http.ResponseWriter, status int, resources []*Resource, links *DocumentLinks, ...) error
• func WriteResponse(w http.ResponseWriter, status int, doc *Document) error
• type Client
  • func NewClient(baseURL string) *Client
  • func (c *Client) Request(req *Request, doc *Document) (*Document, error)
  • func (c *Client) RequestWithResource(req *Request, res *Resource) (*Document, error)
  • func (c *Client) RequestWithResources(req *Request, res []*Resource) (*Document, error)
• type Document
  • func ParseDocument(r io.Reader) (*Document, error)
• type DocumentLinks
• type Error
  • func BadRequest(detail string) *Error
  • func BadRequestParam(detail, param string) *Error
  • func BadRequestPointer(detail, pointer 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
  • func (i Intent) RequestMethod() string
• type Map
  • func StructToMap(source interface{}, fields []string) (Map, error)
  • func (m Map) Assign(target interface{}) error
• type Request
  • func ParseRequest(r *http.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 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 Client

type Client struct {
	// The base URL of the API.
	BaseURL string

	// The underlying http client.
	Client *http.Client
}

Client is a very basic client implementation that simplifies interacting with a JSON API compatible API.

func NewClient

func NewClient(baseURL string) *Client

NewClient creates and returns a new client.

func (*Client) Request

func (c *Client) Request(req *Request, doc *Document) (*Document, error)

Request will make a request using the specified request and an optional document.

func (*Client) RequestWithResource

func (c *Client) RequestWithResource(req *Request, res *Resource) (*Document, error)

RequestWithResource will make a request using the specified request and the passed resource.

func (*Client) RequestWithResources

func (c *Client) RequestWithResources(req *Request, res []*Resource) (*Document, error)

RequestWithResources will make a request using the specified request and the passed resources.

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 ParseDocument

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

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 BadRequestPointer

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

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 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

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.

func StructToMap

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. If no fields to filter are specified, not filtering will be applied.

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

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 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(r *http.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 map representing some of the resource's data.
	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.
	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.