A serializer/deserializer for JSON payloads that comply to the JSON API - jsonapi.org spec in go.
go get -u github.com/google/jsonapi
Or, see Alternative Installation.
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.
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.
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
GOPATHtoPWDin your shell session,export GOPATH=$PWD go get github.com/google/jsonapi. (Append-uaftergetif you are updating.)cd $GOPATH/src/github.com/google/jsonapi/examplesgo build && ./examples
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"`
}`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.
`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.
`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.
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?
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(in io.Reader, model interface{})Visit godoc
MarshalPayload(w io.Writer, models interface{}) errorVisit 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.
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)
}
}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.
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
}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
}If you need to support custom types (e.g. for custom time formats), you'll need to implement the json.Marshaler and json.Unmarshaler interfaces on the type.
// MyTimeFormat is a custom format I invented for fun
const MyTimeFormat = "The time is 15:04:05. The year is 2006, and it is day 2 of January."
// MyTime is a custom type used to handle the custom time format
type MyTime struct {
time.Time
}
// UnmarshalJSON to implement the json.Unmarshaler interface
func (m *MyTime) UnmarshalJSON(b []byte) error {
t, err := time.Parse(MyTimeFormat, string(b))
if err != nil {
return err
}
m.Time = t
return nil
}
// MarshalJSON to implement the json.Marshaler interface
func (m *MyTime) MarshalJSON() ([]byte, error) {
return json.Marshal(m.Time.Format(MyTimeFormat))
}This package also implements support for JSON API compatible errors payloads using the following types.
MarshalErrors(w io.Writer, errs []*ErrorObject) errorWrites a JSON API response using the given []error.
type ErrorsPayload struct {
Errors []*ErrorObject `json:"errors"`
}ErrorsPayload is a serializer struct for representing a valid JSON API errors payload.
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.
// 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
}MarshalOnePayloadEmbedded(w io.Writer, model interface{}) errorVisit 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.
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 ...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.
Fork, Change, Pull Request with tests.