jsonapi

package module
v1.3.1 Latest Latest
Warning

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

 Go to latest Published: Jan 31, 2024 License: MIT Imports: 10 Imported by: 13

README

jsonapi

Build Status Go Report Card GoDoc

A serializer/deserializer for JSON payloads that comply to the JSON API - jsonapi.org v1.1 spec in go.

This package was forked from google/jsonapi and adds several enhancements such as links and polymorphic relationships.

Installation

go get -u github.com/hashicorp/jsonapi

Or, see Alternative Installation.

Background

You are working in your Go web application and you have a struct that is organized similarly to your database schema. You need to send and receive json payloads that adhere to the JSON API spec. Once you realize that your json needed to take on this special form, you go down the path of creating more structs to be able to serialize and deserialize JSON API payloads. Then there are more models required with this additional structure. Ugh! With JSON API, you can keep your model structs as is and use StructTags to indicate to JSON API how you want your response built or your request deserialized. What about your relationships? JSON API supports relationships out of the box and will even put them in your response into an included side-loaded slice--that contains associated records.

Introduction

JSON API uses StructField tags to annotate the structs fields that you already have and use in your app and then reads and writes JSON API output based on the instructions you give the library in your JSON API tags. Let's take an example. In your app, you most likely have structs that look similar to these:

type Blog struct {
	ID            int       `json:"id"`
	Title         string    `json:"title"`
	Posts         []*Post   `json:"posts"`
	CurrentPost   *Post     `json:"current_post"`
	CurrentPostId int       `json:"current_post_id"`
	CreatedAt     time.Time `json:"created_at"`
	ViewCount     int       `json:"view_count"`
}

type Post struct {
	ID       int        `json:"id"`
	BlogID   int        `json:"blog_id"`
	Title    string     `json:"title"`
	Body     string     `json:"body"`
	Comments []*Comment `json:"comments"`
}

type Comment struct {
	Id     int    `json:"id"`
	PostID int    `json:"post_id"`
	Body   string `json:"body"`
	Likes  uint   `json:"likes_count,omitempty"`
}

These structs may or may not resemble the layout of your database. But these are the ones that you want to use right? You wouldn't want to use structs like those that JSON API sends because it is difficult to get at all of your data easily.

Example App

examples/app.go

This program demonstrates the implementation of a create, a show, and a list http.Handler. It outputs some example requests and responses as well as serialized examples of the source/target structs to json. That is to say, I show you that the library has successfully taken your JSON API request and turned it into your struct types.

To run,

  • Make sure you have Go installed
  • Create the following directories or similar: ~/go
  • Set GOPATH to PWD in your shell session, export GOPATH=$PWD
  • go get github.com/hashicorp/jsonapi. (Append -u after get if you are updating.)
  • cd $GOPATH/src/github.com/hashicorp/jsonapi/examples
  • go build && ./examples

jsonapi Tag Reference

Example

The jsonapi StructTags tells this library how to marshal and unmarshal your structs into JSON API payloads and your JSON API payloads to structs, respectively. Then Use JSON API's Marshal and Unmarshal methods to construct and read your responses and replies. Here's an example of the structs above using JSON API tags:

type Blog struct {
	ID            int       `jsonapi:"primary,blogs"`
	Title         string    `jsonapi:"attr,title"`
	Posts         []*Post   `jsonapi:"relation,posts"`
	CurrentPost   *Post     `jsonapi:"relation,current_post"`
	CurrentPostID int       `jsonapi:"attr,current_post_id"`
	CreatedAt     time.Time `jsonapi:"attr,created_at"`
	ViewCount     int       `jsonapi:"attr,view_count"`
}

type Post struct {
	ID       int        `jsonapi:"primary,posts"`
	BlogID   int        `jsonapi:"attr,blog_id"`
	Title    string     `jsonapi:"attr,title"`
	Body     string     `jsonapi:"attr,body"`
	Comments []*Comment `jsonapi:"relation,comments"`
}

type Comment struct {
	ID     int    `jsonapi:"primary,comments"`
	PostID int    `jsonapi:"attr,post_id"`
	Body   string `jsonapi:"attr,body"`
	Likes  uint   `jsonapi:"attr,likes-count,omitempty"`
}
Permitted Tag Values
primary
`jsonapi:"primary,<type field output>"`

This indicates this is the primary key field for this struct type. Tag value arguments are comma separated. The first argument must be, primary, and the second must be the name that should appear in the type* field for all data objects that represent this type of model.

* According the JSON API spec, the plural record types are shown in the examples, but not required.

attr
`jsonapi:"attr,<key name in attributes hash>,<optional: omitempty>"`

These fields' values will end up in the attributeshash for a record. The first argument must be, attr, and the second should be the name for the key to display in the attributes hash for that record. The optional third argument is omitempty - if it is present the field will not be present in the "attributes" if the field's value is equivalent to the field types empty value (ie if the count field is of type int, omitempty will omit the field when count has a value of 0). Lastly, the spec indicates that attributes key names should be dasherized for multiple word field names.

relation
`jsonapi:"relation,<key name in relationships hash>,<optional: omitempty>"`

Relations are struct fields that represent a one-to-one or one-to-many relationship with other structs. JSON API will traverse the graph of relationships and marshal or unmarshal records. The first argument must be, relation, and the second should be the name of the relationship, used as the key in the relationships hash for the record. The optional third argument is omitempty - if present will prevent non existent to-one and to-many from being serialized.

polyrelation
`jsonapi:"polyrelation,<key name in relationships hash>,<optional: omitempty>"`

Polymorphic relations can be represented exactly as relations, except that an intermediate type is needed within your model struct that provides a choice for the actual value to be populated within.

Example:

type Video struct {
	ID          int    `jsonapi:"primary,videos"`
	SourceURL   string `jsonapi:"attr,source-url"`
	CaptionsURL string `jsonapi:"attr,captions-url"`
}

type Image struct {
	ID        int    `jsonapi:"primary,images"`
	SourceURL string `jsonapi:"attr,src"`
	AltText   string `jsonapi:"attr,alt"`
}

type OneOfMedia struct {
	Video *Video
	Image *Image
}

type Post struct {
	ID      int           `jsonapi:"primary,posts"`
	Title   string        `jsonapi:"attr,title"`
	Body    string        `jsonapi:"attr,body"`
	Gallery []*OneOfMedia `jsonapi:"polyrelation,gallery"`
	Hero    *OneOfMedia   `jsonapi:"polyrelation,hero"`
}

During decoding, the polyrelation annotation instructs jsonapi to assign each relationship to either Video or Image within the value of the associated field, provided that the payload contains either a "videos" or "images" type. This field value must be a pointer to a special choice type struct (also known as a tagged union, or sum type) containing other pointer fields to jsonapi models. The actual field assignment depends on that type having a jsonapi "primary" annotation with a type matching the relationship type found in the response. All other fields will be remain empty. If no matching types are represented by the choice type, all fields will be empty.

During encoding, the very first non-nil field will be used to populate the payload. Others will be ignored. Therefore, it's critical to set the value of only one field within the choice struct. When accepting input values on this type of choice type, it would a good idea to enforce and check that the value is set on only one field.

`jsonapi:"links,omitempty"`

A field annotated with links will have the links members of the request unmarshaled to it. Note that this field should always be annotated with omitempty, as marshaling of links members is instead handled by the Linkable interface (see Links below).

Methods Reference

All Marshal and Unmarshal methods expect pointers to struct instance or slices of the same contained with the interface{}s

Now you have your structs prepared to be serialized or materialized, What about the rest?

Create Record Example

You can Unmarshal a JSON API payload using jsonapi.UnmarshalPayload. It reads from an io.Reader containing a JSON API payload for one record (but can have related records). Then, it materializes a struct that you created and passed in (using new or &). Again, the method supports single records only, at the top level, in request payloads at the moment. Bulk creates and updates are not supported yet.

After saving your record, you can use, MarshalOnePayload, to write the JSON API response to an io.Writer.

UnmarshalPayload
UnmarshalPayload(in io.Reader, model interface{})

Visit godoc

MarshalPayload
MarshalPayload(w io.Writer, models interface{}) error

Visit godoc

Writes a JSON API response, with related records sideloaded, into an included array. This method encodes a response for either a single record or many records.

Handler Example Code
func CreateBlog(w http.ResponseWriter, r *http.Request) {
	blog := new(Blog)

	if err := jsonapi.UnmarshalPayload(r.Body, blog); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	// ...save your blog...

	w.Header().Set("Content-Type", jsonapi.MediaType)
	w.WriteHeader(http.StatusCreated)

	if err := jsonapi.MarshalPayload(w, blog); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
	}
}
Create Records Example
UnmarshalManyPayload
UnmarshalManyPayload(in io.Reader, t reflect.Type) ([]interface{}, error)

Visit godoc

Takes an io.Reader and a reflect.Type representing the uniform type contained within the "data" JSON API member.

Handler Example Code
func CreateBlogs(w http.ResponseWriter, r *http.Request) {
	// ...create many blogs at once

	blogs, err := UnmarshalManyPayload(r.Body, reflect.TypeOf(new(Blog)))
	if err != nil {
		t.Fatal(err)
	}

	for _, blog := range blogs {
		b, ok := blog.(*Blog)
		// ...save each of your blogs
	}

	w.Header().Set("Content-Type", jsonapi.MediaType)
	w.WriteHeader(http.StatusCreated)

	if err := jsonapi.MarshalPayload(w, blogs); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
	}
}

If you need to include link objects along with response data, implement the Linkable interface for document-links, and RelationshipLinkable for relationship links:

func (post Post) JSONAPILinks() *Links {
	return &Links{
		"self": "href": fmt.Sprintf("https://example.com/posts/%d", post.ID),
		"comments": Link{
			Href: fmt.Sprintf("https://example.com/api/blogs/%d/comments", post.ID),
			Meta: map[string]interface{}{
				"counts": map[string]uint{
					"likes":    4,
				},
			},
		},
	}
}

// Invoked for each relationship defined on the Post struct when marshaled
func (post Post) JSONAPIRelationshipLinks(relation string) *Links {
	if relation == "comments" {
		return &Links{
			"related": fmt.Sprintf("https://example.com/posts/%d/comments", post.ID),
		}
	}
	return nil
}
Meta

If you need to include meta objects along with response data, implement the Metable interface for document-meta, and RelationshipMetable for relationship meta:

func (post Post) JSONAPIMeta() *Meta {
   return &Meta{
   	"details": "sample details here",
   }
}

// Invoked for each relationship defined on the Post struct when marshaled
func (post Post) JSONAPIRelationshipMeta(relation string) *Meta {
   if relation == "comments" {
   	return &Meta{
   		"this": map[string]interface{}{
   			"can": map[string]interface{}{
   				"go": []interface{}{
   					"as",
   					"deep",
   					map[string]interface{}{
   						"as": "required",
   					},
   				},
   			},
   		},
   	}
   }
   return nil
}
Nullable attributes

Certain APIs may interpret the meaning of null attribute values as significantly different from unspecified values (those that do not show up in the request). The default use of the omitempty struct tag does not allow for sending significant nulls.

A type is provided for this purpose if needed: NullableAttr[T]. This type provides an API for sending and receiving significant null values for attribute values of any type.

In the example below, a payload is presented for a fictitious API that makes use of significant null values. Once enabled, the UnsettableTime setting can only be disabled by updating it to a null value.

The payload struct below makes use of a NullableAttr with an inner time.Time to allow this behavior:

type Settings struct {
	ID             int                              `jsonapi:"primary,videos"`
	UnsettableTime jsonapi.NullableAttr[time.Time]  `jsonapi:"attr,unsettable_time,rfc3339,omitempty"`
}

To enable the setting as described above, an non-null time.Time value is sent to the API. This is done by using the exported NewNullableAttrWithValue[T]() method:

s := Settings{
    ID: 1,
    UnsettableTime: jsonapi.NewNullableAttrWithValue[time.Time](time.Now()),
}

To disable the setting, a null value needs to be sent to the API. This is done by using the exported NewNullNullableAttr[T]() method:

s := Settings{
    ID: 1,
    UnsettableTime: jsonapi.NewNullNullableAttr[time.Time](),
}

Once a payload has been marshaled, the attribute value is flattened to a primitive value:

    "unsettable_time": "2021-01-01T02:07:14Z",

Significant nulls are also included and flattened, even when specifying omitempty:

    "unsettable_time": null,

Once a payload is unmarshaled, the target attribute field is hydrated with the value in the payload and can be retrieved with the Get() method:

t, err := s.UnsettableTime.Get()

All other struct tags used in the attribute definition will be honored when marshaling and unmarshaling non-null values for the inner type.

Custom types

Custom types are supported for primitive types, only, as attributes. Examples,

type CustomIntType int
type CustomFloatType float64
type CustomStringType string

Types like following are not supported, but may be in the future:

type CustomMapType map[string]interface{}
type CustomSliceMapType []map[string]interface{}
Errors

This package also implements support for JSON API compatible errors payloads using the following types.

MarshalErrors
MarshalErrors(w io.Writer, errs []*ErrorObject) error

Writes a JSON API response using the given []error.

ErrorsPayload
type ErrorsPayload struct {
	Errors []*ErrorObject `json:"errors"`
}

ErrorsPayload is a serializer struct for representing a valid JSON API errors payload.

ErrorObject
type ErrorObject struct { ... }

// Error implements the `Error` interface.
func (e *ErrorObject) Error() string {
	return fmt.Sprintf("Error: %s %s\n", e.Title, e.Detail)
}

ErrorObject is an Error implementation as well as an implementation of the JSON API error object.

The main idea behind this struct is that you can use it directly in your code as an error type and pass it directly to MarshalErrors to get a valid JSON API errors payload.

Errors Example Code
// An error has come up in your code, so set an appropriate status, and serialize the error.
if err := validate(&myStructToValidate); err != nil {
	context.SetStatusCode(http.StatusBadRequest) // Or however you need to set a status.
	jsonapi.MarshalErrors(w, []*ErrorObject{{
		Title: "Validation Error",
		Detail: "Given request body was invalid.",
		Status: "400",
		Meta: map[string]interface{}{"field": "some_field", "error": "bad type", "expected": "string", "received": "float64"},
	}})
	return
}

Testing

MarshalOnePayloadEmbedded
MarshalOnePayloadEmbedded(w io.Writer, model interface{}) error

Visit godoc

This method is not strictly meant to for use in implementation code, although feel free. It was mainly created for use in tests; in most cases, your request payloads for create will be embedded rather than sideloaded for related records. This method will serialize a single struct pointer into an embedded json response. In other words, there will be no, included, array in the json; all relationships will be serialized inline with the data.

However, in tests, you may want to construct payloads to post to create methods that are embedded to most closely model the payloads that will be produced by the client. This method aims to enable that.

Example
out := bytes.NewBuffer(nil)

// testModel returns a pointer to a Blog
jsonapi.MarshalOnePayloadEmbedded(out, testModel())

h := new(BlogsHandler)

w := httptest.NewRecorder()
r, _ := http.NewRequest(http.MethodPost, "/blogs", out)

h.CreateBlog(w, r)

blog := new(Blog)
jsonapi.UnmarshalPayload(w.Body, blog)

// ... assert stuff about blog here ...

Alternative Installation

I use git subtrees to manage dependencies rather than go get so that the src is committed to my repo.

git subtree add --squash --prefix=src/github.com/hashicorp/jsonapi https://github.com/hashicorp/jsonapi.git main

To update,

git subtree pull --squash --prefix=src/github.com/hashicorp/jsonapi https://github.com/hashicorp/jsonapi.git main

This assumes that I have my repo structured with a src dir containing a collection of packages and GOPATH is set to the root folder--containing src.

Contributing

Fork, Change, Pull Request with tests.

Documentation

Overview

Package jsonapi provides a serializer and deserializer for jsonapi.org spec payloads.

You can keep your model structs as is and use struct field tags to indicate to jsonapi how you want your response built or your request deserialized. What about my relationships? jsonapi supports relationships out of the box and will even side load them in your response into an "included" array--that contains associated objects.

jsonapi uses StructField tags to annotate the structs fields that you already have and use in your app and then reads and writes jsonapi.org output based on the instructions you give the library in your jsonapi tags.

Example structs using a Blog > Post > Comment structure, 

type Blog struct {
	ID            int       `jsonapi:"primary,blogs"`
	Title         string    `jsonapi:"attr,title"`
	Posts         []*Post   `jsonapi:"relation,posts"`
	CurrentPost   *Post     `jsonapi:"relation,current_post"`
	CurrentPostID int       `jsonapi:"attr,current_post_id"`
	CreatedAt     time.Time `jsonapi:"attr,created_at"`
	ViewCount     int       `jsonapi:"attr,view_count"`
}

type Post struct {
	ID       int        `jsonapi:"primary,posts"`
	BlogID   int        `jsonapi:"attr,blog_id"`
	Title    string     `jsonapi:"attr,title"`
	Body     string     `jsonapi:"attr,body"`
	Comments []*Comment `jsonapi:"relation,comments"`
}

type Comment struct {
	ID     int    `jsonapi:"primary,comments"`
	PostID int    `jsonapi:"attr,post_id"`
	Body   string `jsonapi:"attr,body"`
}

jsonapi Tag Reference

Value, primary: "primary,<type field output>"

This indicates that this is the primary key field for this struct type. Tag value arguments are comma separated. The first argument must be, "primary", and the second must be the name that should appear in the "type" field for all data objects that represent this type of model.

Value, attr: "attr,<key name in attributes hash>[,<extra arguments>]"

These fields' values should end up in the "attribute" hash for a record. The first argument must be, "attr', and the second should be the name for the key to display in the "attributes" hash for that record.

The following extra arguments are also supported:

"omitempty": excludes the fields value from the "attribute" hash. "iso8601": uses the ISO8601 timestamp format when serialising or deserialising the time.Time value.

Value, relation: "relation,<key name in relationships hash>"

Relations are struct fields that represent a one-to-one or one-to-many to other structs. jsonapi will traverse the graph of relationships and marshal or unmarshal records. The first argument must be, "relation", and the second should be the name of the relationship, used as the key in the "relationships" hash for the record.

Use the methods below to Marshal and Unmarshal jsonapi.org json payloads.

Visit the readme at https://github.com/google/jsonapi

Index

Constants

View Source 
const (

	// MediaType is the identifier for the JSON API media type
	//
	// see http://jsonapi.org/format/#document-structure
	MediaType = "application/vnd.api+json"

	// KeyFirstPage is the key to the links object whose value contains a link to
	// the first page of data
	KeyFirstPage = "first"
	// KeyLastPage is the key to the links object whose value contains a link to
	// the last page of data
	KeyLastPage = "last"
	// KeyPreviousPage is the key to the links object whose value contains a link
	// to the previous page of data
	KeyPreviousPage = "prev"
	// KeyNextPage is the key to the links object whose value contains a link to
	// the next page of data
	KeyNextPage = "next"

	// QueryParamPageNumber is a JSON API query parameter used in a page based
	// pagination strategy in conjunction with QueryParamPageSize
	QueryParamPageNumber = "page[number]"
	// QueryParamPageSize is a JSON API query parameter used in a page based
	// pagination strategy in conjunction with QueryParamPageNumber
	QueryParamPageSize = "page[size]"

	// QueryParamPageOffset is a JSON API query parameter used in an offset based
	// pagination strategy in conjunction with QueryParamPageLimit
	QueryParamPageOffset = "page[offset]"
	// QueryParamPageLimit is a JSON API query parameter used in an offset based
	// pagination strategy in conjunction with QueryParamPageOffset
	QueryParamPageLimit = "page[limit]"

	// QueryParamPageCursor is a JSON API query parameter used with a cursor-based
	// strategy
	QueryParamPageCursor = "page[cursor]"

	// KeySelfLink is the key within a top-level links object that denotes the link that
	// generated the current response document.
	KeySelfLink = "self"
)

Variables

View Source 
var (
	// ErrInvalidTime is returned when a struct has a time.Time type field, but
	// the JSON value was not a unix timestamp integer.
	ErrInvalidTime = errors.New("Only numbers can be parsed as dates, unix timestamps")
	// ErrInvalidISO8601 is returned when a struct has a time.Time type field and includes
	// "iso8601" in the tag spec, but the JSON value was not an ISO8601 timestamp string.
	ErrInvalidISO8601 = errors.New("Only strings can be parsed as dates, ISO8601 timestamps")
	// ErrInvalidRFC3339 is returned when a struct has a time.Time type field and includes
	// "rfc3339" in the tag spec, but the JSON value was not an RFC3339 timestamp string.
	ErrInvalidRFC3339 = errors.New("Only strings can be parsed as dates, RFC3339 timestamps")
	// ErrUnknownFieldNumberType is returned when the JSON value was a float
	// (numeric) but the Struct field was a non numeric type (i.e. not int, uint,
	// float, etc)
	ErrUnknownFieldNumberType = errors.New("The struct field was not of a known number type")
	// ErrInvalidType is returned when the given type is incompatible with the expected type.
	ErrInvalidType = errors.New("Invalid type provided") // I wish we used punctuation.
	// ErrTypeNotFound is returned when the given type not found on the model.
	ErrTypeNotFound = errors.New("no primary type annotation found on model")
)
View Source 
var (
	// ErrBadJSONAPIStructTag is returned when the Struct field's JSON API
	// annotation is invalid.
	ErrBadJSONAPIStructTag = errors.New("Bad jsonapi struct tag format")
	// ErrBadJSONAPIID is returned when the Struct JSON API annotated "id" field
	// was not a valid numeric type.
	ErrBadJSONAPIID = errors.New(
		"id should be either string, int(8,16,32,64) or uint(8,16,32,64)")
	// ErrExpectedSlice is returned when a variable or argument was expected to
	// be a slice of *Structs; MarshalMany will return this error when its
	// interface{} argument is invalid.
	ErrExpectedSlice = errors.New("models should be a slice of struct pointers")
	// ErrUnexpectedType is returned when marshalling an interface; the interface
	// had to be a pointer or a slice; otherwise this error is returned.
	ErrUnexpectedType = errors.New("models should be a struct pointer or slice of struct pointers")
	// ErrUnexpectedNil is returned when a slice of relation structs contains nil values
	ErrUnexpectedNil = errors.New("slice of struct pointers cannot contain nil")
)

Functions

func MarshalErrors 

func MarshalErrors(w io.Writer, errorObjects []*ErrorObject) error

MarshalErrors writes a JSON API response using the given `[]error`.

For more information on JSON API error payloads, see the spec here: http://jsonapi.org/format/#document-top-level and here: http://jsonapi.org/format/#error-objects.

func MarshalOnePayloadEmbedded 

func MarshalOnePayloadEmbedded(w io.Writer, model interface{}) error

MarshalOnePayloadEmbedded - This method not meant to for use in implementation code, although feel free. The purpose of this method is for use in tests. In most cases, your request payloads for create will be embedded rather than sideloaded for related records. This method will serialize a single struct pointer into an embedded json response. In other words, there will be no, "included", array in the json all relationships will be serailized inline in the data.

However, in tests, you may want to construct payloads to post to create methods that are embedded to most closely resemble the payloads that will be produced by the client. This is what this method is intended for.

model interface{} should be a pointer to a struct.

func MarshalPayload 

func MarshalPayload(w io.Writer, models interface{}) error

MarshalPayload writes a jsonapi response for one or many records. The related records are sideloaded into the "included" array. If this method is given a struct pointer as an argument it will serialize in the form "data": {...}. If this method is given a slice of pointers, this method will serialize in the form "data": [...]

One Example: you could pass it, w, your http.ResponseWriter, and, models, a ptr to a Blog to be written to the response body: 

 func ShowBlog(w http.ResponseWriter, r *http.Request) {
	 blog := &Blog{}

	 w.Header().Set("Content-Type", jsonapi.MediaType)
	 w.WriteHeader(http.StatusOK)

	 if err := jsonapi.MarshalPayload(w, blog); err != nil {
		 http.Error(w, err.Error(), http.StatusInternalServerError)
	 }
 }

Many Example: you could pass it, w, your http.ResponseWriter, and, models, a slice of Blog struct instance pointers to be written to the response body: 

	 func ListBlogs(w http.ResponseWriter, r *http.Request) {
    blogs := []*Blog{}

		 w.Header().Set("Content-Type", jsonapi.MediaType)
		 w.WriteHeader(http.StatusOK)

		 if err := jsonapi.MarshalPayload(w, blogs); err != nil {
			 http.Error(w, err.Error(), http.StatusInternalServerError)
		 }
	 }

func MarshalPayloadWithoutIncluded 

func MarshalPayloadWithoutIncluded(w io.Writer, model interface{}) error

MarshalPayloadWithoutIncluded writes a jsonapi response with one or many records, without the related records sideloaded into "included" array. If you want to serialize the relations into the "included" array see MarshalPayload.

models interface{} should be either a struct pointer or a slice of struct pointers.

func UnmarshalManyPayload 

func UnmarshalManyPayload(in io.Reader, t reflect.Type) ([]interface{}, error)

UnmarshalManyPayload converts an io into a set of struct instances using jsonapi tags on the type's struct fields.

func UnmarshalPayload 

func UnmarshalPayload(in io.Reader, model interface{}) error

UnmarshalPayload converts an io into a struct instance using jsonapi tags on struct fields. This method supports single request payloads only, at the moment. Bulk creates and updates are not supported yet.

Will Unmarshal embedded and sideloaded payloads. The latter is only possible if the object graph is complete. That is, in the "relationships" data there are type and id, keys that correspond to records in the "included" array.

For example you could pass it, in, req.Body and, model, a BlogPost struct instance to populate in an http handler, 

func CreateBlog(w http.ResponseWriter, r *http.Request) {
	blog := new(Blog)

	if err := jsonapi.UnmarshalPayload(r.Body, blog); err != nil {
		http.Error(w, err.Error(), 500)
		return
	}

	// ...do stuff with your blog...

	w.Header().Set("Content-Type", jsonapi.MediaType)
	w.WriteHeader(201)

	if err := jsonapi.MarshalPayload(w, blog); err != nil {
		http.Error(w, err.Error(), 500)
	}
}

Visit https://github.com/google/jsonapi#create for more info.

model interface{} should be a pointer to a struct.

Types

type ErrUnsupportedPtrType 

type ErrUnsupportedPtrType struct {
	// contains filtered or unexported fields
}

ErrUnsupportedPtrType is returned when the Struct field was a pointer but the JSON value was of a different type

func (ErrUnsupportedPtrType) Error 

func (eupt ErrUnsupportedPtrType) Error() string

type ErrorObject 

type ErrorObject struct {
	// ID is a unique identifier for this particular occurrence of a problem.
	ID string `json:"id,omitempty"`

	// Title is a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
	Title string `json:"title,omitempty"`

	// Detail is a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
	Detail string `json:"detail,omitempty"`

	// Status is the HTTP status code applicable to this problem, expressed as a string value.
	Status string `json:"status,omitempty"`

	// Code is an application-specific error code, expressed as a string value.
	Code string `json:"code,omitempty"`

	// Meta is an object containing non-standard meta-information about the error.
	Meta *map[string]interface{} `json:"meta,omitempty"`
}

ErrorObject is an `Error` implementation as well as an implementation of the JSON API error object.

The main idea behind this struct is that you can use it directly in your code as an error type and pass it directly to `MarshalErrors` to get a valid JSON API errors payload. For more information on Golang errors, see: https://golang.org/pkg/errors/ For more information on the JSON API spec's error objects, see: http://jsonapi.org/format/#error-objects

func (*ErrorObject) Error 

func (e *ErrorObject) Error() string

Error implements the `Error` interface.

type ErrorsPayload 

type ErrorsPayload struct {
	Errors []*ErrorObject `json:"errors"`
}

ErrorsPayload is a serializer struct for representing a valid JSON API errors payload.

type Event 

type Event int

Event represents a lifecycle event in the marshaling or unmarshalling process. 

const (
	// UnmarshalStart is the Event that is sent when deserialization of a payload
	// begins.
	UnmarshalStart Event = iota

	// UnmarshalStop is the Event that is sent when deserialization of a payload
	// ends.
	UnmarshalStop

	// MarshalStart is the Event that is sent sent when serialization of a payload
	// begins.
	MarshalStart

	// MarshalStop is the Event that is sent sent when serialization of a payload
	// ends.
	MarshalStop
)

type Events 

type Events func(*Runtime, Event, string, time.Duration)

Events is the func type that provides the callback for handling event timings. 

var Instrumentation Events

Instrumentation is a a global Events variable. This is the handler for all timing events. 

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

Link is used to represent a member of the `links` object.

type Linkable 

type Linkable interface {
	JSONAPILinks() *Links
}

Linkable is used to include document links in response data e.g. {"self": "http://example.com/posts/1"} 

type Links map[string]interface{}

Links is used to represent a `links` object. http://jsonapi.org/format/#document-links

type ManyPayload 

type ManyPayload struct {
	Data     []*Node `json:"data"`
	Included []*Node `json:"included,omitempty"`
	Links    *Links  `json:"links,omitempty"`
	Meta     *Meta   `json:"meta,omitempty"`
}

ManyPayload is used to represent a generic JSON API payload where many resources (Nodes) were included in an [] in the "data" key

type Meta 

type Meta map[string]interface{}

Meta is used to represent a `meta` object. http://jsonapi.org/format/#document-meta

type Metable 

type Metable interface {
	JSONAPIMeta() *Meta
}

Metable is used to include document meta in response data e.g. {"foo": "bar"}

type Node 

type Node struct {
	Type          string                 `json:"type"`
	ID            string                 `json:"id,omitempty"`
	ClientID      string                 `json:"client-id,omitempty"`
	Attributes    map[string]interface{} `json:"attributes,omitempty"`
	Relationships map[string]interface{} `json:"relationships,omitempty"`
	Links         *Links                 `json:"links,omitempty"`
	Meta          *Meta                  `json:"meta,omitempty"`
}

Node is used to represent a generic JSON API Resource

type NullableAttr added in v1.3.0 

type NullableAttr[T any] map[bool]T

NullableAttr is a generic type, which implements a field that can be one of three states:

- field is not set in the request - field is explicitly set to `null` in the request - field is explicitly set to a valid value in the request

NullableAttr is intended to be used with JSON marshalling and unmarshalling. This is generally useful for PATCH requests, where attributes with zero values are intentionally not marshaled into the request payload so that existing attribute values are not overwritten.

Internal implementation details:

- map[true]T means a value was provided - map[false]T means an explicit null was provided - nil or zero map means the field was not provided

If the field is expected to be optional, add the `omitempty` JSON tags. Do NOT use `*NullableAttr`!

Adapted from https://www.jvt.me/posts/2024/01/09/go-json-nullable/

func NewNullNullableAttr added in v1.3.0 

func NewNullNullableAttr[T any]() NullableAttr[T]

NewNullNullableAttr is a convenience helper to allow constructing a NullableAttr with an explicit `null`, for instance to construct a field inside a struct without introducing an intermediate variable

func NewNullableAttrWithValue added in v1.3.0 

func NewNullableAttrWithValue[T any](t T) NullableAttr[T]

NewNullableAttrWithValue is a convenience helper to allow constructing a NullableAttr with a given value, for instance to construct a field inside a struct without introducing an intermediate variable.

func (NullableAttr[T]) Get added in v1.3.0 

func (t NullableAttr[T]) Get() (T, error)

Get retrieves the underlying value, if present, and returns an error if the value was not present

func (NullableAttr[T]) IsNull added in v1.3.0 

func (t NullableAttr[T]) IsNull() bool

IsNull indicate whether the field was sent, and had a value of `null`

func (NullableAttr[T]) IsSpecified added in v1.3.0 

func (t NullableAttr[T]) IsSpecified() bool

IsSpecified indicates whether the field was sent

func (*NullableAttr[T]) Set added in v1.3.0 

func (t *NullableAttr[T]) Set(value T)

Set sets the underlying value to a given value

func (*NullableAttr[T]) SetInterface added in v1.3.0 

func (t *NullableAttr[T]) SetInterface(value interface{})

Set sets the underlying value to a given value

func (*NullableAttr[T]) SetNull added in v1.3.0 

func (t *NullableAttr[T]) SetNull()

SetNull sets the value to an explicit `null`

func (*NullableAttr[T]) SetUnspecified added in v1.3.0 

func (t *NullableAttr[T]) SetUnspecified()

SetUnspecified sets the value to be absent from the serialized payload

type OnePayload 

type OnePayload struct {
	Data     *Node   `json:"data"`
	Included []*Node `json:"included,omitempty"`
	Links    *Links  `json:"links,omitempty"`
	Meta     *Meta   `json:"meta,omitempty"`
}

OnePayload is used to represent a generic JSON API payload where a single resource (Node) was included as an {} in the "data" key

type Payloader 

type Payloader interface {
	// contains filtered or unexported methods
}

Payloader is used to encapsulate the One and Many payload types

func Marshal 

func Marshal(models interface{}) (Payloader, error)

Marshal does the same as MarshalPayload except it just returns the payload and doesn't write out results. Useful if you use your own JSON rendering library.

type RelationshipLinkable 

type RelationshipLinkable interface {
	// JSONAPIRelationshipLinks will be invoked for each relationship with the corresponding relation name (e.g. `comments`)
	JSONAPIRelationshipLinks(relation string) *Links
}

RelationshipLinkable is used to include relationship links in response data e.g. {"related": "http://example.com/posts/1/comments"}

type RelationshipManyNode 

type RelationshipManyNode struct {
	Data  []*Node `json:"data"`
	Links *Links  `json:"links,omitempty"`
	Meta  *Meta   `json:"meta,omitempty"`
}

RelationshipManyNode is used to represent a generic has many JSON API relation

type RelationshipMetable 

type RelationshipMetable interface {
	// JSONRelationshipMeta will be invoked for each relationship with the corresponding relation name (e.g. `comments`)
	JSONAPIRelationshipMeta(relation string) *Meta
}

RelationshipMetable is used to include relationship meta in response data

type RelationshipOneNode 

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

RelationshipOneNode is used to represent a generic has one JSON API relation

type Runtime 

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime has the same methods as jsonapi package for serialization and deserialization but also has a ctx, a map[string]interface{} for storing state, designed for instrumenting serialization timings.

func NewRuntime 

func NewRuntime() *Runtime

NewRuntime creates a Runtime for use in an application.

func (*Runtime) Instrument 

func (r *Runtime) Instrument(key string) *Runtime

Instrument is deprecated.

func (*Runtime) MarshalPayload 

func (r *Runtime) MarshalPayload(w io.Writer, model interface{}) error

MarshalPayload has docs in response.go for MarshalPayload.

func (*Runtime) UnmarshalManyPayload 

func (r *Runtime) UnmarshalManyPayload(reader io.Reader, kind reflect.Type) (elems []interface{}, err error)

UnmarshalManyPayload has docs in request.go for UnmarshalManyPayload.

func (*Runtime) UnmarshalPayload 

func (r *Runtime) UnmarshalPayload(reader io.Reader, model interface{}) error

UnmarshalPayload has docs in request.go for UnmarshalPayload.

func (*Runtime) Value 

func (r *Runtime) Value(key string) interface{}

Value returns a state variable in the runtime context.

func (*Runtime) WithValue 

func (r *Runtime) WithValue(key string, value interface{}) *Runtime

WithValue adds custom state variables to the runtime context.

Source Files

View all Source files

Directories

Path Synopsis

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.