fastjsonapi

package module
v0.0.0-...-172b716 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2016 License: MIT Imports: 14 Imported by: 2

README

fastjsonapi

Build Status

A fasthttp fork of the Google serailizer/deserializer for json payloads that comply to the JSON API - jsonapi.org spec in go.

Also visit, Godoc.

Extra Features

This fork offers:

  • fasthttp integration
  • easyjson for non-reflection based de/serialisation of JSON
  • satori/go.uuid support

Installation

go get -u github.com/google/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 runnable file 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
  • cd there
  • Set GOPATH to PWD in your shell session, export GOPATH=$PWD
  • go get github.com/google/jsonapi. (Append -u after get if you are updating.)
  • go run src/github.com/google/jsonapi/examples/app.go or cd src/github.com/google/jsonapi/examples && go run app.go

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

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.

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

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

Visit godoc

Writes a JSON API response, with related records sideloaded, into an included array. This method encodes a response for a single record only. If you want to serialize many records, see, MarshalManyPayload.

Handler Example Code
func CreateBlog(ctx *fasthttp.RequestCtx) {
	blog := new(Blog)

	if err := fastjsonapi.UnmarshalPayload(r.Body, blog); err != nil {
		ctx.Error(err.Error(), fasthttp.StatusInternalServerError)
		return
	}

	// ...save your blog...

	w.WriteHeader(201)
	w.Header().Set("Content-Type", "application/vnd.api+json")

	if err := jsonapi.MarshalOnePayload(w, blog); err != nil {
		http.Error(w, err.Error(), fasthttp.StatusInternalServerError)
	}
}
List Records Example
MarshalManyPayload
MarshalManyPayload(w io.Writer, models []interface{}) error

Visit godoc

Takes an io.Writer and an slice of interface{}. Note, if you have a type safe array of your structs, like,

var blogs []*Blog

you will need to iterate over the slice of Blog pointers and append them to an interface array, like,

blogInterface := make([]interface{}, len(blogs))

for i, blog := range blogs {
  blogInterface[i] = blog
}

Alternatively, you can insert your Blogs into a slice of interface{} the first time. For example when you fetch the Blogs from the db append them to an []interface{} rather than a []*Blog. So your method signature to reach into your data store may look something like this,

func FetchBlogs() ([]interface{}, error)
Handler Example Code
func ListBlogs(w http.ResponseWriter, r *http.Request) {
	// ...fetch your blogs, filter, offset, limit, etc...

  // but, for now
	blogs := testBlogsForList()

	w.WriteHeader(200)
	w.Header().Set("Content-Type", "application/vnd.api+json")
	if err := jsonapi.MarshalManyPayload(w, blogs); err != nil {
		http.Error(w, err.Error(), fasthttp.StatusInternalServerError)
	}
}

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
fastjsonapi.MarshalOnePayloadEmbedded(out, testModel())

blogHandler := func(ctx *fasthttp.RequestCtx) {
        // ... fasthttp.RequestHandler for blogs
}

ctx := fasthttp.RequestCtx{}
ctx.Request.Header.SetMethod("POST")
ctx.Request.SetRequestURI("/blogs")
ctx.Request.SetBody(out.Bytes())

blogHandler(ctx)

blog := new(Blog)
fastjsonapi.UnmarshalPayload(ctx.Response.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/google/jsonapi https://github.com/google/jsonapi.git master

To update,

git subtree pull --squash --prefix=src/github.com/google/jsonapi https://github.com/google/jsonapi.git master

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 fastjsonapi provides a fasthttp based 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 deserialzied. 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"`
}

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

This section is empty.

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")
	// 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")
	// ErrUnsupportedPtrType is returned when the Struct field was a pointer but
	// the JSON value was of a different type
	ErrUnsupportedPtrType = errors.New("Pointer type in struct is not supported")
)
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 arugment 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")
)
View Source 
var ContentType = []byte("application/vnd.api+json")

Functions

func MarshalManyPayload 

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

MarshalManyPayload writes a jsonapi response with many records, with related records sideloaded, into "included" array. This method encodes a response for a slice of records, hence data will be an array of records rather than a single record. To serialize a single record, see MarshalOnePayload

For example you could pass it, w, your http.ResponseWriter, and, models, a slice of Blog struct instance pointers as interface{}'s to write to the response, 

 func ListBlogs(w http.ResponseWriter, r *http.Request) {
	 // ... fetch your blogs and filter, offset, limit, etc ...

	 blogs := testBlogsForList()

	 w.WriteHeader(200)
	 w.Header().Set("Content-Type", "application/vnd.api+json")
	 if err := jsonapi.MarshalManyPayload(w, blogs); err != nil {
		 http.Error(w, err.Error(), 500)
	 }
 }

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

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

func MarshalOnePayload 

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

MarshalOnePayload writes a jsonapi response with one, with related records sideloaded, into "included" array. This method encodes a response for a single record only. Hence, data will be a single record rather than an array of records. If you want to serialize many records, see, MarshalManyPayload.

See UnmarshalPayload for usage example.

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

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 MarshalOnePayloadWithoutIncluded 

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

MarshalOnePayloadWithoutIncluded writes a jsonapi response with one object, without the related records sideloaded into "included" array. If you want to serialzie the realtions into the "included" array see MarshalOnePayload.

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

func UnmarshalManyPayload 

func UnmarshalManyPayload(data []byte, t reflect.Type) ([]interface{}, error)

func UnmarshalPayload 

func UnmarshalPayload(data []byte, 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.WriteHeader(201)
	w.Header().Set("Content-Type", "application/vnd.api+json")

	if err := jsonapi.MarshalOnePayload(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 Event 

type Event int
const (
	UnmarshalStart Event = iota
	UnmarshalStop
	MarshalStart
	MarshalStop
)

type Events 

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

type ManyPayload 

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

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

func MarshalMany 

func MarshalMany(models []interface{}) (*ManyPayload, error)

MarshalMany does the same as MarshalManyPayload except it just returns the payload and doesn't write out results. Useful is you use your JSON rendering library.

func (ManyPayload) MarshalEasyJSON 

func (v ManyPayload) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (ManyPayload) MarshalJSON 

func (v ManyPayload) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*ManyPayload) UnmarshalEasyJSON 

func (v *ManyPayload) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*ManyPayload) UnmarshalJSON 

func (v *ManyPayload) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Node 

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

Node is used to represent a generic JSON API Resource

func (Node) MarshalEasyJSON 

func (v Node) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Node) MarshalJSON 

func (v Node) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Node) UnmarshalEasyJSON 

func (v *Node) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Node) UnmarshalJSON 

func (v *Node) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type OnePayload 

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

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

func MarshalOne 

func MarshalOne(model interface{}) (*OnePayload, error)

MarshalOne does the same as MarshalOnePayload except it just returns the payload and doesn't write out results. Useful is you use your JSON rendering library.

func (OnePayload) MarshalEasyJSON 

func (v OnePayload) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (OnePayload) MarshalJSON 

func (v OnePayload) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*OnePayload) UnmarshalEasyJSON 

func (v *OnePayload) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*OnePayload) UnmarshalJSON 

func (v *OnePayload) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type RelationshipManyNode 

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

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

func (RelationshipManyNode) MarshalEasyJSON 

func (v RelationshipManyNode) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (RelationshipManyNode) MarshalJSON 

func (v RelationshipManyNode) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*RelationshipManyNode) UnmarshalEasyJSON 

func (v *RelationshipManyNode) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*RelationshipManyNode) UnmarshalJSON 

func (v *RelationshipManyNode) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type RelationshipOneNode 

type RelationshipOneNode struct {
	Data  *Node              `json:"data"`
	Links *map[string]string `json:"links,omitempty"`
}

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

func (RelationshipOneNode) MarshalEasyJSON 

func (v RelationshipOneNode) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (RelationshipOneNode) MarshalJSON 

func (v RelationshipOneNode) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*RelationshipOneNode) UnmarshalEasyJSON 

func (v *RelationshipOneNode) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*RelationshipOneNode) UnmarshalJSON 

func (v *RelationshipOneNode) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Runtime 

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

func NewRuntime 

func NewRuntime() *Runtime

func (*Runtime) Instrument 

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

func (*Runtime) MarshalManyPayload 

func (r *Runtime) MarshalManyPayload(w io.Writer, models interface{}) error

func (*Runtime) MarshalOnePayload 

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

func (*Runtime) MarshalOnePayloadEmbedded 

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

func (*Runtime) UnmarshalManyPayload 

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

func (*Runtime) UnmarshalPayload 

func (r *Runtime) UnmarshalPayload(data []byte, model interface{}) error

func (*Runtime) Value 

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

func (*Runtime) WithValue 

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

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.