tjsonapi

package module
v0.0.0-...-9ef80fd Latest Latest
Warning

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

 Go to latest Published: Sep 23, 2016 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).

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.