Merge branch 'feature/meta'

Author: aren55555

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/google/jsonapi.svg?branch=master)](https://travis-ci.org/google/jsonapi) [![GoDoc](https://godoc.org/github.com/google/jsonapi?status.svg)](http://godoc.org/github.com/google/jsonapi)
 
-A serializer/deserializer for json payloads that comply to the
+A serializer/deserializer for JSON payloads that comply to the
 [JSON API - jsonapi.org](http://jsonapi.org) spec in go.
 
 ## Installation
@@ -364,6 +364,38 @@ func (post Post) JSONAPIRelationshipLinks(relation string) *Links {
 }
 ```
 
+### Meta
+
+ If you need to include [meta objects](http://jsonapi.org/format/#document-meta) along with response data, implement the `Metable` interface for document-meta, and `RelationshipMetable` for relationship meta:
+
+ ```go
+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
+}
+```
+
 ### Errors
 This package also implements support for JSON API compatible `errors` payloads using the following types.
 

examples/app.go

@@ -43,7 +43,7 @@ func exerciseHandler() {
 	// list
 	req, _ := http.NewRequest(http.MethodGet, "/blogs", nil)
 
-	req.Header.Set("Accept", jsonapi.MediaType)
+	req.Header.Set(headerAccept, jsonapi.MediaType)
 
 	w := httptest.NewRecorder()
 
@@ -60,7 +60,7 @@ func exerciseHandler() {
 	// show
 	req, _ = http.NewRequest(http.MethodGet, "/blogs?id=1", nil)
 
-	req.Header.Set("Accept", jsonapi.MediaType)
+	req.Header.Set(headerAccept, jsonapi.MediaType)
 
 	w = httptest.NewRecorder()
 
@@ -81,7 +81,7 @@ func exerciseHandler() {
 
 	req, _ = http.NewRequest(http.MethodPost, "/blogs", in)
 
-	req.Header.Set("Accept", jsonapi.MediaType)
+	req.Header.Set(headerAccept, jsonapi.MediaType)
 
 	w = httptest.NewRecorder()
 
@@ -107,7 +107,7 @@ func exerciseHandler() {
 
 	req, _ = http.NewRequest(http.MethodPut, "/blogs", in)
 
-	req.Header.Set("Accept", jsonapi.MediaType)
+	req.Header.Set(headerAccept, jsonapi.MediaType)
 
 	w = httptest.NewRecorder()
 

examples/models.go

@@ -3,6 +3,8 @@ package main
 import (
 	"fmt"
 	"time"
+
+	"github.com/google/jsonapi"
 )
 
 type Blog struct {
@@ -30,22 +32,43 @@ type Comment struct {
 }
 
 // Blog Links
-func (blog Blog) JSONAPILinks() *map[string]interface{} {
-	return &map[string]interface{}{
+func (blog Blog) JSONAPILinks() *jsonapi.Links {
+	return &jsonapi.Links{
 		"self": fmt.Sprintf("https://example.com/blogs/%d", blog.ID),
 	}
 }
 
-func (blog Blog) JSONAPIRelationshipLinks(relation string) *map[string]interface{} {
+func (blog Blog) JSONAPIRelationshipLinks(relation string) *jsonapi.Links {
 	if relation == "posts" {
-		return &map[string]interface{}{
+		return &jsonapi.Links{
 			"related": fmt.Sprintf("https://example.com/blogs/%d/posts", blog.ID),
 		}
 	}
 	if relation == "current_post" {
-		return &map[string]interface{}{
+		return &jsonapi.Links{
 			"related": fmt.Sprintf("https://example.com/blogs/%d/current_post", blog.ID),
 		}
 	}
 	return nil
 }
+
+// Blog Meta
+func (blog Blog) JSONAPIMeta() *jsonapi.Meta {
+	return &jsonapi.Meta{
+		"detail": "extra details regarding the blog",
+	}
+}
+
+func (blog Blog) JSONAPIRelationshipMeta(relation string) *jsonapi.Meta {
+	if relation == "posts" {
+		return &jsonapi.Meta{
+			"detail": "posts meta information",
+		}
+	}
+	if relation == "current_post" {
+		return &jsonapi.Meta{
+			"detail": "current post meta information",
+		}
+	}
+	return nil
+}

models_test.go

@@ -0,0 +1,157 @@
+package jsonapi
+
+import (
+	"fmt"
+	"time"
+)
+
+type BadModel struct {
+	ID int `jsonapi:"primary"`
+}
+
+type ModelBadTypes struct {
+	ID           string     `jsonapi:"primary,badtypes"`
+	StringField  string     `jsonapi:"attr,string_field"`
+	FloatField   float64    `jsonapi:"attr,float_field"`
+	TimeField    time.Time  `jsonapi:"attr,time_field"`
+	TimePtrField *time.Time `jsonapi:"attr,time_ptr_field"`
+}
+
+type WithPointer struct {
+	ID       *uint64  `jsonapi:"primary,with-pointers"`
+	Name     *string  `jsonapi:"attr,name"`
+	IsActive *bool    `jsonapi:"attr,is-active"`
+	IntVal   *int     `jsonapi:"attr,int-val"`
+	FloatVal *float32 `jsonapi:"attr,float-val"`
+}
+
+type Timestamp struct {
+	ID   int        `jsonapi:"primary,timestamps"`
+	Time time.Time  `jsonapi:"attr,timestamp,iso8601"`
+	Next *time.Time `jsonapi:"attr,next,iso8601"`
+}
+
+type Car struct {
+	ID    *string `jsonapi:"primary,cars"`
+	Make  *string `jsonapi:"attr,make,omitempty"`
+	Model *string `jsonapi:"attr,model,omitempty"`
+	Year  *uint   `jsonapi:"attr,year,omitempty"`
+}
+
+type Post struct {
+	Blog
+	ID            uint64     `jsonapi:"primary,posts"`
+	BlogID        int        `jsonapi:"attr,blog_id"`
+	ClientID      string     `jsonapi:"client-id"`
+	Title         string     `jsonapi:"attr,title"`
+	Body          string     `jsonapi:"attr,body"`
+	Comments      []*Comment `jsonapi:"relation,comments"`
+	LatestComment *Comment   `jsonapi:"relation,latest_comment"`
+}
+
+type Comment struct {
+	ID       int    `jsonapi:"primary,comments"`
+	ClientID string `jsonapi:"client-id"`
+	PostID   int    `jsonapi:"attr,post_id"`
+	Body     string `jsonapi:"attr,body"`
+}
+
+type Book struct {
+	ID          uint64  `jsonapi:"primary,books"`
+	Author      string  `jsonapi:"attr,author"`
+	ISBN        string  `jsonapi:"attr,isbn"`
+	Title       string  `jsonapi:"attr,title,omitempty"`
+	Description *string `jsonapi:"attr,description"`
+	Pages       *uint   `jsonapi:"attr,pages,omitempty"`
+	PublishedAt time.Time
+	Tags        []string `jsonapi:"attr,tags"`
+}
+
+type Blog struct {
+	ID            int       `jsonapi:"primary,blogs"`
+	ClientID      string    `jsonapi:"client-id"`
+	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"`
+}
+
+func (b *Blog) JSONAPILinks() *Links {
+	return &Links{
+		"self": fmt.Sprintf("https://example.com/api/blogs/%d", b.ID),
+		"comments": Link{
+			Href: fmt.Sprintf("https://example.com/api/blogs/%d/comments", b.ID),
+			Meta: Meta{
+				"counts": map[string]uint{
+					"likes":    4,
+					"comments": 20,
+				},
+			},
+		},
+	}
+}
+
+func (b *Blog) JSONAPIRelationshipLinks(relation string) *Links {
+	if relation == "posts" {
+		return &Links{
+			"related": Link{
+				Href: fmt.Sprintf("https://example.com/api/blogs/%d/posts", b.ID),
+				Meta: Meta{
+					"count": len(b.Posts),
+				},
+			},
+		}
+	}
+	if relation == "current_post" {
+		return &Links{
+			"self": fmt.Sprintf("https://example.com/api/posts/%s", "3"),
+			"related": Link{
+				Href: fmt.Sprintf("https://example.com/api/blogs/%d/current_post", b.ID),
+			},
+		}
+	}
+	return nil
+}
+
+func (b *Blog) JSONAPIMeta() *Meta {
+	return &Meta{
+		"detail": "extra details regarding the blog",
+	}
+}
+
+func (b *Blog) JSONAPIRelationshipMeta(relation string) *Meta {
+	if relation == "posts" {
+		return &Meta{
+			"this": map[string]interface{}{
+				"can": map[string]interface{}{
+					"go": []interface{}{
+						"as",
+						"deep",
+						map[string]interface{}{
+							"as": "required",
+						},
+					},
+				},
+			},
+		}
+	}
+	if relation == "current_post" {
+		return &Meta{
+			"detail": "extra current_post detail",
+		}
+	}
+	return nil
+}
+
+type BadComment struct {
+	ID   uint64 `jsonapi:"primary,bad-comment"`
+	Body string `jsonapi:"attr,body"`
+}
+
+func (bc *BadComment) JSONAPILinks() *Links {
+	return &Links{
+		"self": []string{"invalid", "should error"},
+	}
+}

node.go

@@ -8,6 +8,7 @@ type OnePayload 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
@@ -16,6 +17,7 @@ type ManyPayload struct {
 	Data     []*Node `json:"data"`
 	Included []*Node `json:"included,omitempty"`
 	Links    *Links  `json:"links,omitempty"`
+	Meta     *Meta   `json:"meta,omitempty"`
 }
 
 // Node is used to represent a generic JSON API Resource
@@ -26,19 +28,22 @@ type Node struct {
 	Attributes    map[string]interface{} `json:"attributes,omitempty"`
 	Relationships map[string]interface{} `json:"relationships,omitempty"`
 	Links         *Links                 `json:"links,omitempty"`
+	Meta          *Meta                  `json:"meta,omitempty"`
 }
 
 // RelationshipOneNode is used to represent a generic has one JSON API relation
 type RelationshipOneNode 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 RelationshipManyNode struct {
 	Data  []*Node `json:"data"`
 	Links *Links  `json:"links,omitempty"`
+	Meta  *Meta   `json:"meta,omitempty"`
 }
 
 // Links is used to represent a `links` object.
@@ -69,8 +74,8 @@ func (l *Links) validate() (err error) {
 
 // Link is used to represent a member of the `links` object.
 type Link struct {
-	Href string                 `json:"href"`
-	Meta map[string]interface{} `json:"meta,omitempty"`
+	Href string `json:"href"`
+	Meta Meta   `json:"meta,omitempty"`
 }
 
 // Linkable is used to include document links in response data
@@ -85,3 +90,19 @@ type RelationshipLinkable interface {
 	// JSONAPIRelationshipLinks will be invoked for each relationship with the corresponding relation name (e.g. `comments`)
 	JSONAPIRelationshipLinks(relation string) *Links
 }
+
+// Meta is used to represent a `meta` object.
+// http://jsonapi.org/format/#document-meta
+type Meta map[string]interface{}
+
+// Metable is used to include document meta in response data
+// e.g. {"foo": "bar"}
+type Metable interface {
+	JSONAPIMeta() *Meta
+}
+
+// RelationshipMetable is used to include relationship meta in response data
+type RelationshipMetable interface {
+	// JSONRelationshipMeta will be invoked for each relationship with the corresponding relation name (e.g. `comments`)
+	JSONAPIRelationshipMeta(relation string) *Meta
+}

request_test.go

@@ -11,26 +11,6 @@ import (
 	"time"
 )
 
-type BadModel struct {
-	ID int `jsonapi:"primary"`
-}
-
-type WithPointer struct {
-	ID       *uint64  `jsonapi:"primary,with-pointers"`
-	Name     *string  `jsonapi:"attr,name"`
-	IsActive *bool    `jsonapi:"attr,is-active"`
-	IntVal   *int     `jsonapi:"attr,int-val"`
-	FloatVal *float32 `jsonapi:"attr,float-val"`
-}
-
-type ModelBadTypes struct {
-	ID           string     `jsonapi:"primary,badtypes"`
-	StringField  string     `jsonapi:"attr,string_field"`
-	FloatField   float64    `jsonapi:"attr,float_field"`
-	TimeField    time.Time  `jsonapi:"attr,time_field"`
-	TimePtrField *time.Time `jsonapi:"attr,time_ptr_field"`
-}
-
 func TestUnmarshall_attrStringSlice(t *testing.T) {
 	out := &Book{}
 	tags := []string{"fiction", "sale"}