tjsonapi

package module
v0.0.0-...-431ed0d Latest Latest
Warning

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

Go to latest
Published: Dec 1, 2017 License: LGPL-3.0 Imports: 6 Imported by: 0

README

tjsonapi

Golang helper utility for using JSON API (http://jsonapi.org/) structures.

Documentation

Index

Constants

View Source
const (
	// ResourceLinkageToOne represents an identifier for to-one resource
	// linkages to use as type.
	ResourceLinkageToOne = 0

	// ResourceLinkageToMany represents an identifier for to-many resource
	// linkages to use as type.
	ResourceLinkageToMany = 1
)
View Source
const (
	// ResourcesOne represents an identifier for resources objects that only
	// contain one resource.
	ResourcesOne = 0

	// ResourcesMany represents an identifier for resources object that contain
	// multiple resource objects.
	ResourcesMany = 1
)
View Source
const (
	// TagIdentifier is the top-level tag used to define a value as an
	// identifier.
	TagIdentifier = "identifier"

	// TagAttribute is the top-level tag used to define a value as an
	// attribute.
	TagAttribute = "attribute"

	// TagRelationship is the top-level tag used to mark a value as a
	// relationship.
	TagRelationship = "relationship"

	// TagLink is the top-level tag used to define a value as a link.
	TagLink = "link"

	// TagMeta is the top-level tag used to define a value as a part of the
	// meta object.
	TagMeta = "meta"

	// TagValue is the tag used when populating structs of a context. Member
	// marked with this tag can and will be set to a specific value when
	// using contexted members.
	TagValue = "value"

	// TagRelationshipContext is the sub-tag used to define a value as a
	// context relationship.
	TagRelationshipContext = "context"

	// TagRelationshipLink is the sub-tag used to define a value as a link
	// relationship.
	TagRelationshipLink = "link"

	// TagRelationshipData is the sub-tag used to define a value as a resource
	// linkage relationship.
	TagRelationshipData = "data"

	// TagLinkContext is the sub-tag used to define a value as a context link.
	TagLinkContext = "context"
)

Variables

View Source
var (
	// ErrAttributeInvalidKey is an error object returned when a relationships
	// or a links member is added to the attributes object.
	ErrAttributeInvalidKey = errors.New("The attributes object must not " +
		"contain a relationships or links member")

	// ErrAttributeNotFound is an error object returned when the user tries
	// to access an attribute that does not exists in a attributes object.
	ErrAttributeNotFound = errors.New("Attribute not found")
)
View Source
var (
	// ErrDecodingInvalidType is an error object that is returned when the
	// interface sent to Unmarshal mismatches the Resources object (e.g. not
	// a pointer when Resources is "One" or not a slice when Resources is
	// "many").
	ErrDecodingInvalidType = errors.New("Interface has invalid type")

	// ErrDecodingInvalidIDType is an error object that is returned when the
	// type specified in the JSONAPI identifier tag doesn't match the one in
	// the decoded data.
	ErrDecodingInvalidIDType = errors.New("Struct has invalid identifier type")

	// ErrDecodingInvalidTag is an error object that is returned when the tag
	// for a field is invalid (e.g. when is a tag is unknown, or when the tag
	// doesn't contain enough sub-tags).
	ErrDecodingInvalidTag = errors.New("Invalid JSONAPI tag")

	// ErrCantSet is an error object that is returned when a value can't be
	// set to another.
	ErrCantSet = errors.New("Can't set")
)
View Source
var (
	// ErrEncodingInvalidType is an error object that is returned when the
	// value send to marshal is not a struct.
	ErrEncodingInvalidType = errors.New("Encoding JSONAPI from invalid type")

	// ErrEncodingInvalidTag is an error object that is returned when the
	// tag for a field is invalid (e.g. when a tag is unknown, or when
	// the tag doesn't contain enough sub-tags).
	ErrEncodingInvalidTag = errors.New("Invalid JSONAPI tag")
)
View Source
var (
	// ErrLinkNotFound is an error object returned when the user tries to
	// access a link that does not exists in a links object.
	ErrLinkNotFound = errors.New("Link not found")

	// ErrLinkUnsupportedType is an error object returned when the user
	// tries to marshal a link of unsupported type (e.g. neither string or
	// Link).
	ErrLinkUnsupportedType = errors.New("Link is of unsupported type")

	// ErrLinkNoMeta is an error object returned when the user tries to
	// retrieve the meta object of a link that doesn't have any. When the link
	// type is Link, it is ensured to have a meta object, although it may be
	// empty.
	ErrLinkNoMeta = errors.New("Link has no meta object")
)
View Source
var (
	// ErrContextNotFound is an error object returned when a value is not
	// found in a particular context.
	ErrContextNotFound = errors.New("Value not found in context")
)
View Source
var (
	// ErrInvalidJSONValue is an error object returned when the value is of
	// a type that can't be marshalled into a JSON value.
	ErrInvalidJSONValue = errors.New("Value is not JSON compatible")
)
View Source
var (
	// ErrMetaNotFound is an error object returned when the user tries to
	// access a meta member that does not exists in a meta object.
	ErrMetaNotFound = errors.New("Meta not found")
)
View Source
var (
	// ErrResourceLinkageBadType is an error object returned when the user
	// tries to do a to-many operation on a to-one resource linkage and
	// vice-versa.
	ErrResourceLinkageBadType = errors.New("Mismatched types on resource " +
		"linkage")
)
View Source
var (
	// ErrResourcesBadType is an error object returned when the user tries to
	// use a "many" resources object as a "one", and vice-versa.
	ErrResourcesBadType = errors.New("Mismatched types on resources")
)

Functions

func Unmarshal

func Unmarshal(r *Root, v interface{}) error

Unmarshal fills up an interface from a JSONAPI root. This function is equivalent to creating a blank Context and unmarshaling the root with it. See Context.Unmarshal for more details.

Types

type Attributes

type Attributes map[string]interface{}

Attributes is a map that associates string values with any JSON-compatible type, effectively representing a Attributes object as defined in the <a href="http://jsonapi.org/format/#document-resource-object-attributes"> JSON API</a>.

func NewAttributes

func NewAttributes() Attributes

NewAttributes allocates a new map and returns it as an Attribute value. This function is the equivalent of calling make(map[string]interface{}).

func (Attributes) AddAttribute

func (a Attributes) AddAttribute(key string, value interface{}) error

AddAttribute adds and associates a value to a given key. It fails and returns an error if the key is reserved by the JSON API or if the type of the value is not marshalable by Go's JSON package. This method is the equivalent of assigning the value to a[key], with added sanity checks.

func (Attributes) GetAttribute

func (a Attributes) GetAttribute(key string) (interface{}, error)

GetAttribute tries to return the attribute associated with the given key. If the attribute is not found, this method returns a nil value with an error.

type Context

type Context struct {
	Relationships Relationships
	Links         map[string]*Link
}

Context is a struct allowing the user to add links and relationships models to use with the `jsonapi:"...,context"` tag.

func NewContext

func NewContext() *Context

NewContext allocates and initializes a new Context object and returns it.

func (*Context) Marshal

func (c *Context) Marshal(i interface{}) (*Root, error)

Marshal returns a JSON-marshalable root for the given interface, using c as the Context.

func (*Context) Unmarshal

func (c *Context) Unmarshal(r *Root, i interface{}) error

Unmarshal fills up an interface from a JSONAPI root, using c as the Context.

type Link struct {
	HRef string                 `json:"href"`
	Meta map[string]interface{} `json:"meta"`
}

Link is a struct that represents a link object from the <a href="http://jsonapi.org/format/#document-links">JSON API</a>.

func NewLink() *Link

NewLink allocates, initializes and returns a new Link object.

type Links map[string]interface{}

Links is a map that associates string values with either *Link or string values, effectively representing a links object as defined in the <a href="http://jsonapi.org/format/#document-links">JSON API</a>.

func NewLinks() Links

NewLinks allocates a new map and returns it as a Links value. The function is the equivalent to calling make(map[string]interface{}).

func (l Links) AddLink(key string, link string)

AddLink adds and associates a string to a given key. This function is the equivalent of assigning the string to l[key].

func (Links) AddLinkObject

func (l Links) AddLinkObject(key string, linkObject *Link)

AddLinkObject adds and associates a Link object to a given key. This function is the equivalent of assigning the link to l[key].

func (l Links) GetLink(key string) (string, error)

GetLink tries to return the string representation of the link associated with the given key. If the link is a Link object, its HRef attribute will be returned. If the link is not found or of inappropriate type, an empty string will be returned along with the associated error.

func (Links) GetLinkMeta

func (l Links) GetLinkMeta(key string) (map[string]interface{}, error)

GetLinkMeta tries to return the meta object of the link object associated with the given key. If the link is either not found, of inappropriate type or doesn't have a meta object, a nil map will be returned along with the associated error.

type Meta

type Meta map[string]interface{}

Meta is a map that associates string values with any JSON-compatible type, representing a Meta object as defined in the <a href="http://jsonapi.org/format/#document-meta">JSON API</a>.

func NewMeta

func NewMeta() Meta

NewMeta allocates a new map and returns it as a Meta value. This function is the equivalent of doing make(map[string]interface{}).

func (Meta) AddMeta

func (m Meta) AddMeta(key string, value interface{}) error

AddMeta adds and associates a value to a given key. If the value is not a valid JSON value, an error is returned. This method is the equivalent of assigning the value to m[key], with added sanity checks.

func (Meta) GetMeta

func (m Meta) GetMeta(key string) (interface{}, error)

GetMeta tries to return the meta member associated with the given key. If the member is not found, this method returns a nil value with an error.

type Relationship

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

Relationship is a struct that represents a relationship object from the <a href="http://jsonapi.org/format/#document-resource-object-relationships"> JSON API</a>.

func NewRelationship

func NewRelationship() *Relationship

NewRelationship allocates, initializes and returns a Relationship object.

type Relationships

type Relationships map[string]*Relationship

Relationships is a map that associates string values with *Relationship values, effectively representing a relationships object as defined in the <a href="http://jsonapi.org/format/#document-resource-object-relationships"> JSON API</a>.

func NewRelationships

func NewRelationships() Relationships

NewRelationships allocates a new map and returns it as a Relationships value. This function is the equivalent to calling make(map[string]*Relationship).

type Resource

type Resource struct {
	ID            string        `json:"id"`
	Type          string        `json:"type"`
	Attributes    Attributes    `json:"attributes,omitempty"`
	Relationships Relationships `json:"relationships,omitempty"`
	Links         Links         `json:"links,omitempty"`
	Meta          Meta          `json:"meta,omitempty"`
}

Resource is a struct that represents a resource object from the <a href="http://jsonapi.org/format/#document-resource-objects">JSON API</a>.

func NewResource

func NewResource() *Resource

NewResource allocates and initializes a new Resource object, and returns it.

type ResourceIdentifier

type ResourceIdentifier struct {
	ID   string `json:"id"`
	Type string `json:"type"`
	Meta Meta   `json:"meta,omitempty"`
}

ResourceIdentifier is a struct that represents a resource linkage object from the <a href="http://jsonapi.org/format/#document-resource-object-linkage">JSON API</a>.

func NewResourceIdentifier

func NewResourceIdentifier() *ResourceIdentifier

NewResourceIdentifier allocates and initializes a new ResourceIdentifier object.

type ResourceLinkage

type ResourceLinkage struct {
	Type uint8
	Data []*ResourceIdentifier
}

ResourceLinkage is a struct representing a ResourceLinkage object from the <a href="http://jsonapi.org/format/#document-resource-object-linkage">JSON API</a>. To support both to-one and to-many linkages, the struct contains a type and a resource identifier slice.

func NewResourceLinkageToMany

func NewResourceLinkageToMany() *ResourceLinkage

NewResourceLinkageToMany allocates and initializes a ResourceLinkage object with ResourceLinkageToMany as type.

func NewResourceLinkageToOne

func NewResourceLinkageToOne() *ResourceLinkage

NewResourceLinkageToOne allocates and initializes a ResourceLinkage object with ResourceLinkageToOne as type.

func (*ResourceLinkage) AddResourceIdentifier

func (l *ResourceLinkage) AddResourceIdentifier(r *ResourceIdentifier) error

AddResourceIdentifier adds a ResourceIdentifier object to a to-many ResourceLinkage. If the ResourceLinkage is to-one, does nothing and returns an error.

func (*ResourceLinkage) GetResourceIdentifier

func (l *ResourceLinkage) GetResourceIdentifier() (*ResourceIdentifier, error)

GetResourceIdentifier tries to return the ResourceIdentifier object contained in a ResourceLinkage object. If this function is used in a to-many context, it does nothing and returns an error.

func (*ResourceLinkage) GetResourceIdentifiers

func (l *ResourceLinkage) GetResourceIdentifiers() ([]*ResourceIdentifier,
	error)

GetResourceIdentifiers tries to return the internal ResourceIdentifier slice of a ResourceLinkage object. Although it's possible to get a single-item slice for to-one ResourceLinkage, this function returns an error when the user attempts it, because it is considered as a to-many operation.

func (*ResourceLinkage) MarshalJSON

func (l *ResourceLinkage) MarshalJSON() ([]byte, error)

MarshalJSON marshals a ResourceLinkage to JSON. This method is needed because a ResourceLinkage object is in fact a multi-type object.<br /> If the ResourceLinkage is to-one, the value of the first and unique element of the underlying slice is marshaled. If the ResourceLinkage is to-many, the entire slice is then marshaled.

func (*ResourceLinkage) SetResourceIdentifier

func (l *ResourceLinkage) SetResourceIdentifier(r *ResourceIdentifier) error

SetResourceIdentifier sets the ResourceIdentifier object of a to-one ResourceLinkage. If the ResourceLinkage is to-many, does nothing and returns an error.

func (*ResourceLinkage) UnmarshalJSON

func (l *ResourceLinkage) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals JSON data to a ResourceLinkage object. Can fail if the JSON data does not represent an object or an array.

type Resources

type Resources struct {
	Type uint8
	Data []*Resource
}

Resources is a struct representing a resources object from the <a href="http://jsonapi.org/format/#document-resource-objects">JSON API</a>. To support the ability of having either a single resource or multiple resources, the struct contains a type and a resource slice.

func NewResourcesMany

func NewResourcesMany() *Resources

NewResourcesMany allocates and initializes a Resources object with ResourcesMany as type.

func NewResourcesOne

func NewResourcesOne() *Resources

NewResourcesOne allocates and initializes a Resources object with ResourcesOne as type.

func (*Resources) AddResource

func (r *Resources) AddResource(resource *Resource) error

AddResource adds a Resource object to a Resources object. If the Resources object doesn't support multiple resources, an error is returned.

func (*Resources) GetResource

func (r *Resources) GetResource() (*Resource, error)

GetResource tries to return the single Resource object of a Resources object. If the Resources object is of "many" type, returns an error.

func (*Resources) GetResources

func (r *Resources) GetResources() ([]*Resource, error)

GetResources tries to return the internal Resource slice of a Resources object. If the Resources object is meant to be used as a single-value resource, returns an error instead, as GetResource should be used instead.

func (*Resources) MarshalJSON

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

MarshalJSON marshals a Resources object to JSON. This method is needed because a Resources object is in fact a multi-type object.<br /> If there is many resources in the object, the entire slice is marshaled, but if there is only one, only the first element is marshaled.

func (*Resources) SetResource

func (r *Resources) SetResource(resource *Resource) error

SetResource sets the Resource object of a Resources object. If the Resources object supports multiple resources instead, an error is returned.

func (*Resources) UnmarshalJSON

func (r *Resources) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals JSON data to a Resources object. Can fail if the JSON data does not represent an object or an array.

type Root

type Root struct {
	Data *Resources `json:"data,omitempty"`
	Meta Meta       `json:"meta,omitempty"`
}

Root is a struct that represents the top-level object of a <a href="http://jsonapi.org/format/#document-top-level">JSON API</a> document.

func Marshal

func Marshal(v interface{}) (*Root, error)

Marshal returns a JSON-marshalable root for the given interface. This function is equivalent to creating a blank Context and marshaling the interface with it. See Context.Marshal for more details.

func NewRoot

func NewRoot() *Root

NewRoot allocates a new Root object. Equivalent to new(Root).

Jump to

Keyboard shortcuts

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