jsonapi

README

api2go JSONAPI package

This package contains JSON API compatible marshal und unmarshal functionality.

  go get github.com/manyminds/api2go/jsonapi

Usage

For information on how to use this package, please refer to the documentation on the api2go main project, the integration_test.go or the godoc.

Documentation

Index

• func Jsonify(s string) string
• func Marshal(data interface{}) ([]byte, error)
• func MarshalWithURLs(data interface{}, information ServerInformation) ([]byte, error)
• func Pluralize(word string) string
• func Unmarshal(data []byte, target interface{}) error
• type Data
• type DataContainer
  • func (c *DataContainer) MarshalJSON() ([]byte, error)
  • func (c *DataContainer) UnmarshalJSON(payload []byte) error
• type Document
  • func MarshalToStruct(data interface{}, information ServerInformation) (*Document, error)
• type EditToManyRelations
• type EntityNamer
• type Link
  • func (l Link) Empty() bool
  • func (l Link) MarshalJSON() ([]byte, error)
  • func (l *Link) UnmarshalJSON(payload []byte) error
• type Links
• type MarshalCustomLinks
• type MarshalCustomRelationshipMeta
• type MarshalIdentifier
• type MarshalIncludedRelations
• type MarshalLinkedRelations
• type MarshalMeta
• type MarshalReferences
• type Meta
• type Reference
• type ReferenceID
• type Relationship
• type RelationshipData
• type RelationshipDataContainer
  • func (c *RelationshipDataContainer) MarshalJSON() ([]byte, error)
  • func (c *RelationshipDataContainer) UnmarshalJSON(payload []byte) error
• type RelationshipType
• type ServerInformation
• type UnmarshalIdentifier
• type UnmarshalResourceMeta
• type UnmarshalToManyRelations
• type UnmarshalToOneRelations

Functions

func Jsonify

func Jsonify(s string) string

Jsonify returns a JSON formatted key name from a go struct field name.

func Marshal

func Marshal(data interface{}) ([]byte, error)

Marshal wraps data in a Document and returns its JSON encoding.

Data can be a struct, a pointer to a struct or a slice of structs. All structs must at least implement the `MarshalIdentifier` interface.

func MarshalWithURLs

func MarshalWithURLs(data interface{}, information ServerInformation) ([]byte, error)

MarshalWithURLs can be used to pass along a ServerInformation implementor.

func Pluralize

func Pluralize(word string) string

Pluralize returns the pluralization of a noun.

func Unmarshal

func Unmarshal(data []byte, target interface{}) error

Unmarshal parses a JSON API compatible JSON and populates the target which must implement the `UnmarshalIdentifier` interface.

Types

type Data

type Data struct {
	Type          string                  `json:"type"`
	ID            string                  `json:"id"`
	Attributes    json.RawMessage         `json:"attributes"`
	Relationships map[string]Relationship `json:"relationships,omitempty"`
	Links         Links                   `json:"links,omitempty"`
	Meta          json.RawMessage         `json:"meta,omitempty"`
}

Data is a general struct for document data and included data.

type DataContainer

type DataContainer struct {
	DataObject *Data
	DataArray  []Data
}

A DataContainer is used to marshal and unmarshal single objects and arrays of objects.

func (*DataContainer) MarshalJSON

func (c *DataContainer) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of the DataArray field or the DataObject field. It will return "null" if neither of them is set.

func (*DataContainer) UnmarshalJSON

func (c *DataContainer) UnmarshalJSON(payload []byte) error

UnmarshalJSON unmarshals the JSON-encoded data to the DataObject field if the root element is an object or to the DataArray field for arrays.

type Document

type Document struct {
	Links    Links                  `json:"links,omitempty"`
	Data     *DataContainer         `json:"data"`
	Included []Data                 `json:"included,omitempty"`
	Meta     map[string]interface{} `json:"meta,omitempty"`
}

A Document represents a JSON API document as specified here: http://jsonapi.org.

func MarshalToStruct

func MarshalToStruct(data interface{}, information ServerInformation) (*Document, error)

MarshalToStruct marshals an api2go compatible struct into a jsonapi Document structure which then can be marshaled to JSON. You only need this method if you want to extract or extend parts of the document. You should directly use Marshal to get a []byte with JSON in it.

type EditToManyRelations

type EditToManyRelations interface {
	AddToManyIDs(name string, IDs []string) error
	DeleteToManyIDs(name string, IDs []string) error
}

The EditToManyRelations interface can be optionally implemented to add and delete to-many relationships on a already unmarshalled struct. These methods are used by our API for the to-many relationship update routes.

There are 3 HTTP Methods to edit to-many relations:

PATCH /v1/posts/1/comments
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
	{ "type": "comments", "id": "2" },
	{ "type": "comments", "id": "3" }
  ]
}

This replaces all of the comments that belong to post with ID 1 and the SetToManyReferenceIDs method will be called.

POST /v1/posts/1/comments
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
	{ "type": "comments", "id": "123" }
  ]
}

Adds a new comment to the post with ID 1. The AddToManyIDs method will be called.

DELETE /v1/posts/1/comments
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": [
	{ "type": "comments", "id": "12" },
	{ "type": "comments", "id": "13" }
  ]
}

Deletes comments that belong to post with ID 1. The DeleteToManyIDs method will be called.

type EntityNamer

type EntityNamer interface {
	GetName() string
}

The EntityNamer interface can be optionally implemented to directly return the name of resource used for the "type" field.

Note: By default the name is guessed from the struct name.

type Link

type Link struct {
	Href string `json:"href"`
	Meta Meta   `json:"meta,omitempty"`
}

Link represents a link for return in the document.

func (Link) Empty

func (l Link) Empty() bool

Empty returns true if the link has no href and no metadata.

func (Link) MarshalJSON

func (l Link) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of only the Href field if the Meta field is empty, otherwise it marshals the whole struct.

func (*Link) UnmarshalJSON

func (l *Link) UnmarshalJSON(payload []byte) error

UnmarshalJSON marshals a string value into the Href field or marshals an object value into the whole struct.

type Links

type Links map[string]Link

Links contains a map of custom Link objects as given by an element.

type MarshalCustomLinks

type MarshalCustomLinks interface {
	MarshalIdentifier
	GetCustomLinks(string) Links
}

The MarshalCustomLinks interface can be implemented if the struct should want any custom links.

type MarshalCustomRelationshipMeta

type MarshalCustomRelationshipMeta interface {
	MarshalIdentifier
	GetCustomMeta(string) map[string]Meta
}

The MarshalCustomRelationshipMeta interface can be implemented if the struct should want a custom meta in a relationship.

type MarshalIdentifier

type MarshalIdentifier interface {
	GetID() string
}

The MarshalIdentifier interface is necessary to give an element a unique ID.

Note: The implementation of this interface is mandatory.

type MarshalIncludedRelations

type MarshalIncludedRelations interface {
	MarshalReferences
	MarshalIdentifier
	GetReferencedStructs() []MarshalIdentifier
}

The MarshalIncludedRelations interface must be implemented if referenced structs should be included in the document.

type MarshalLinkedRelations

type MarshalLinkedRelations interface {
	MarshalReferences
	MarshalIdentifier
	GetReferencedIDs() []ReferenceID
}

The MarshalLinkedRelations interface must be implemented if there are reference ids that should be included in the document.

type MarshalMeta

type MarshalMeta interface {
	MarshalIdentifier
	Meta() Meta
}

The MarshalMeta interface can be implemented if the struct should want any meta.

type MarshalReferences

type MarshalReferences interface {
	GetReferences() []Reference
}

The MarshalReferences interface must be implemented if the struct to be serialized has relationships.

type Meta

type Meta map[string]interface{}

Meta contains unstructured metadata

type Reference

type Reference struct {
	Type         string
	Name         string
	IsNotLoaded  bool
	Relationship RelationshipType
}

A Reference information about possible references of a struct.

Note: If IsNotLoaded is set to true, the `data` field will be omitted and only the `links` object will be generated. You should do this if there are some references, but you do not want to load them. Otherwise, if IsNotLoaded is false and GetReferencedIDs() returns no IDs for this reference name, an empty `data` field will be added which means that there are no references.

type ReferenceID

type ReferenceID struct {
	ID           string
	Type         string
	Name         string
	Relationship RelationshipType
}

ReferenceID contains all necessary information in order to reference another struct in JSON API.

type Relationship

type Relationship struct {
	Links Links                      `json:"links,omitempty"`
	Data  *RelationshipDataContainer `json:"data,omitempty"`
	Meta  map[string]interface{}     `json:"meta,omitempty"`
}

Relationship contains reference IDs to the related structs

type RelationshipData

type RelationshipData struct {
	Type string `json:"type"`
	ID   string `json:"id"`
}

RelationshipData represents one specific reference ID.

type RelationshipDataContainer

type RelationshipDataContainer struct {
	DataObject *RelationshipData
	DataArray  []RelationshipData
}

A RelationshipDataContainer is used to marshal and unmarshal single relationship objects and arrays of relationship objects.

func (*RelationshipDataContainer) MarshalJSON

func (c *RelationshipDataContainer) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of the DataArray field or the DataObject field. It will return "null" if neither of them is set.

func (*RelationshipDataContainer) UnmarshalJSON

func (c *RelationshipDataContainer) UnmarshalJSON(payload []byte) error

UnmarshalJSON unmarshals the JSON-encoded data to the DataObject field if the root element is an object or to the DataArray field for arrays.

type RelationshipType

type RelationshipType int

RelationshipType specifies the type of a relationship.

const (
	DefaultRelationship RelationshipType = iota
	ToOneRelationship
	ToManyRelationship
)

The available relationship types.

Note: DefaultRelationship guesses the relationship type based on the pluralization of the reference name.

type ServerInformation

type ServerInformation interface {
	GetBaseURL() string
	GetPrefix() string
}

A ServerInformation implementor can be passed to MarshalWithURLs to generate the `self` and `related` urls inside `links`.

type UnmarshalIdentifier

type UnmarshalIdentifier interface {
	SetID(string) error
}

The UnmarshalIdentifier interface must be implemented to set the ID during unmarshalling.

type UnmarshalResourceMeta

type UnmarshalResourceMeta interface {
	MarshalIdentifier
	SetResourceMeta(json.RawMessage) error
}

The UnmarshalResourceMeta interface must be implemented to unmarshal meta fields inside of data containers

type UnmarshalToManyRelations

type UnmarshalToManyRelations interface {
	SetToManyReferenceIDs(name string, IDs []string) error
}

The UnmarshalToManyRelations interface must be implemented to unmarshal to-many relations.

type UnmarshalToOneRelations

type UnmarshalToOneRelations interface {
	SetToOneReferenceID(name, ID string) error
}

The UnmarshalToOneRelations interface must be implemented to unmarshal to-one relations.