jsonapi/README.md

jsonapi

A serailizer/deserializer for json payloads that comply to the jsonapi.org spec in go.

Background

You are working in your Go web application and you have a struct that is similar to how your datbase table looks. You need to send and receive json payloads that adhere jsonapi spec. Once you realized that your json needed to take on this special form, you went down the path of creating more structs to be able to serialize and deserialize jsonapi payloads. Then more models required these additional structure. Ugh! In comes jsonapi. 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.

Introduction

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

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 jsonapi sends because it is very hard to get at all of your data easily.

Tags Example

You want jsonapi.org style inputs and ouputs but you want to keep your structs that you already have. Use the jsonapi lib with the "jsonapi" tag on your struct fields along with its Marshal and Unmarshal methods to construct and read your responses and replies, respectively. Here's an example of the structs above using jsonapi 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"`
}

Handler Examples

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 are prepared to be seralized or materialized. What about the rest?

Create

You can Unmarshal a jsonapi payload using jsonapi.UnmarshalPayload; convert an io into a struct instance using jsonapi tags on struct fields. Method supports single request payloads only, at the moment. Bulk creates and updates are not supported yet.

UnmarshalPayload

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

Visit godoc

MarshalOnePayload

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

Visit godoc

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

Example

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)
	}
}

List

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 interate 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,

FetchBlogs() ([]interface{}, error)

Example

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)
	}
}

Testing

MarshalOnePayloadEmbedded

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

Visit godoc

This method not meant to for use in implementation code, although feel free. This method was 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 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 resember 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.

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("POST", "/blogs", out)

h.CreateBlog(w, r)

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

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

Contributing

Fork, Change, Pull Request with tests.