Allow elements to implement custom links (#278)

* Custom marshaler for string links

Author: icgood

api.go

@@ -70,7 +70,7 @@ func (p paginationQueryParams) isValid() bool {
 }
 
 func (p paginationQueryParams) getLinks(r *http.Request, count uint, info information) (result jsonapi.Links, err error) {
-	result = jsonapi.Links{}
+	result = make(jsonapi.Links)
 
 	params := r.URL.Query()
 	prefix := ""
@@ -91,11 +91,11 @@ func (p paginationQueryParams) getLinks(r *http.Request, count uint, info inform
 		if p.number != "1" {
 			params.Set("page[number]", "1")
 			query, _ := url.QueryUnescape(params.Encode())
-			result.First = fmt.Sprintf("%s?%s", requestURL, query)
+			result["first"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 
 			params.Set("page[number]", strconv.FormatUint(number-1, 10))
 			query, _ = url.QueryUnescape(params.Encode())
-			result.Previous = fmt.Sprintf("%s?%s", requestURL, query)
+			result["prev"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 		}
 
 		// calculate last page number
@@ -113,11 +113,11 @@ func (p paginationQueryParams) getLinks(r *http.Request, count uint, info inform
 		if number != totalPages {
 			params.Set("page[number]", strconv.FormatUint(number+1, 10))
 			query, _ := url.QueryUnescape(params.Encode())
-			result.Next = fmt.Sprintf("%s?%s", requestURL, query)
+			result["next"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 
 			params.Set("page[number]", strconv.FormatUint(totalPages, 10))
 			query, _ = url.QueryUnescape(params.Encode())
-			result.Last = fmt.Sprintf("%s?%s", requestURL, query)
+			result["last"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 		}
 	} else {
 		// we have offset & limit params
@@ -134,7 +134,7 @@ func (p paginationQueryParams) getLinks(r *http.Request, count uint, info inform
 		if p.offset != "0" {
 			params.Set("page[offset]", "0")
 			query, _ := url.QueryUnescape(params.Encode())
-			result.First = fmt.Sprintf("%s?%s", requestURL, query)
+			result["first"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 
 			var prevOffset uint64
 			if limit > offset {
@@ -144,18 +144,18 @@ func (p paginationQueryParams) getLinks(r *http.Request, count uint, info inform
 			}
 			params.Set("page[offset]", strconv.FormatUint(prevOffset, 10))
 			query, _ = url.QueryUnescape(params.Encode())
-			result.Previous = fmt.Sprintf("%s?%s", requestURL, query)
+			result["prev"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 		}
 
 		// check if there are more entries to be loaded
 		if (offset + limit) < uint64(count) {
 			params.Set("page[offset]", strconv.FormatUint(offset+limit, 10))
 			query, _ := url.QueryUnescape(params.Encode())
-			result.Next = fmt.Sprintf("%s?%s", requestURL, query)
+			result["next"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 
 			params.Set("page[offset]", strconv.FormatUint(uint64(count)-limit, 10))
 			query, _ = url.QueryUnescape(params.Encode())
-			result.Last = fmt.Sprintf("%s?%s", requestURL, query)
+			result["last"] = jsonapi.Link{Href: fmt.Sprintf("%s?%s", requestURL, query)}
 		}
 	}
 
@@ -926,7 +926,7 @@ func (res *resource) respondWithPagination(obj Responder, info information, stat
 		return err
 	}
 
-	data.Links = &links
+	data.Links = links
 	meta := obj.Metadata()
 	if len(meta) > 0 {
 		data.Meta = meta

jsonapi/data_structs.go

@@ -8,10 +8,11 @@ import (
 
 var objectSuffix = []byte("{")
 var arraySuffix = []byte("[")
+var stringSuffix = []byte(`"`)
 
 // A Document represents a JSON API document as specified here: http://jsonapi.org.
 type Document struct {
-	Links    *Links                 `json:"links,omitempty"`
+	Links    Links                  `json:"links,omitempty"`
 	Data     *DataContainer         `json:"data"`
 	Included []Data                 `json:"included,omitempty"`
 	Meta     map[string]interface{} `json:"meta,omitempty"`
@@ -48,28 +49,64 @@ func (c *DataContainer) MarshalJSON() ([]byte, error) {
 	return json.Marshal(c.DataObject)
 }
 
-// Links is a general struct for document links and relationship links.
-type Links struct {
-	Self     string `json:"self,omitempty"`
-	Related  string `json:"related,omitempty"`
-	First    string `json:"first,omitempty"`
-	Previous string `json:"prev,omitempty"`
-	Next     string `json:"next,omitempty"`
-	Last     string `json:"last,omitempty"`
+// Link represents a link for return in the document.
+type Link struct {
+	Href string                 `json:"href"`
+	Meta map[string]interface{} `json:"meta,omitempty"`
 }
 
+// UnmarshalJSON marshals a string value into the Href field or marshals an
+// object value into the whole struct.
+func (l *Link) UnmarshalJSON(payload []byte) error {
+	if bytes.HasPrefix(payload, stringSuffix) {
+		return json.Unmarshal(payload, &l.Href)
+	}
+
+	if bytes.HasPrefix(payload, objectSuffix) {
+		obj := make(map[string]interface{})
+		err := json.Unmarshal(payload, &obj)
+		if err != nil {
+			return err
+		}
+		var ok bool
+		l.Href, ok = obj["href"].(string)
+		if !ok {
+			return errors.New(`link object expects a "href" key`)
+		}
+		l.Meta, _ = obj["meta"].(map[string]interface{})
+		return nil
+	}
+
+	return errors.New("expected a JSON encoded string or object")
+}
+
+// MarshalJSON returns the JSON encoding of only the Href field if the Meta
+// field is empty, otherwise it marshals the whole struct.
+func (l Link) MarshalJSON() ([]byte, error) {
+	if len(l.Meta) == 0 {
+		return json.Marshal(l.Href)
+	}
+	return json.Marshal(map[string]interface{}{
+		"href": l.Href,
+		"meta": l.Meta,
+	})
+}
+
+// Links contains a map of custom Link objects as given by an element.
+type Links map[string]Link
+
 // Data is a general struct for document data and included data.
 type Data struct {
 	Type          string                  `json:"type"`
 	ID            string                  `json:"id"`
 	Attributes    json.RawMessage         `json:"attributes"`
 	Relationships map[string]Relationship `json:"relationships,omitempty"`
-	Links         *Links                  `json:"links,omitempty"`
+	Links         Links                   `json:"links,omitempty"`
 }
 
 // Relationship contains reference IDs to the related structs
 type Relationship struct {
-	Links *Links                     `json:"links,omitempty"`
+	Links Links                      `json:"links,omitempty"`
 	Data  *RelationshipDataContainer `json:"data,omitempty"`
 	Meta  map[string]interface{}     `json:"meta,omitempty"`
 }

jsonapi/data_structs_test.go

@@ -160,4 +160,76 @@ var _ = Describe("JSONAPI Struct tests", func() {
 		Expect(err).ToNot(HaveOccurred())
 		Expect(target.Data.DataArray).To(Equal([]Data{expectedData}))
 	})
+
+	Context("Marshal and Unmarshal link structs", func() {
+		It("marshals to a string with no metadata", func() {
+			link := Link{Href: "test link"}
+			ret, err := json.Marshal(&link)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ret).To(MatchJSON(`"test link"`))
+		})
+
+		It("marshals to an object with metadata", func() {
+			link := Link{
+				Href: "test link",
+				Meta: map[string]interface{}{
+					"test": "data",
+				},
+			}
+			ret, err := json.Marshal(&link)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(ret).To(MatchJSON(`{
+				"href": "test link",
+				"meta": {"test": "data"}
+			}`))
+		})
+
+		It("unmarshals from a string", func() {
+			expected := Link{Href: "test link"}
+			target := Link{}
+			err := json.Unmarshal([]byte(`"test link"`), &target)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(target).To(Equal(expected))
+		})
+
+		It("unmarshals from an object", func() {
+			expected := Link{
+				Href: "test link",
+				Meta: map[string]interface{}{
+					"test": "data",
+				},
+			}
+			target := Link{}
+			err := json.Unmarshal([]byte(`{
+				"href": "test link",
+				"meta": {"test": "data"}
+			}`), &target)
+			Expect(err).ToNot(HaveOccurred())
+			Expect(target).To(Equal(expected))
+		})
+
+		It("unmarshals with an error when href is missing", func() {
+			err := json.Unmarshal([]byte(`{}`), &Link{})
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(Equal(`link object expects a "href" key`))
+		})
+
+		It("unmarshals with an error for syntax error", func() {
+			badPayloads := []string{`{`, `"`}
+			for _, payload := range badPayloads {
+				err := json.Unmarshal([]byte(payload), &Link{})
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(Equal("unexpected end of JSON input"))
+			}
+		})
+
+		It("unmarshals with an error for wrong types", func() {
+			badPayloads := []string{`null`, `13`, `[]`}
+			for _, payload := range badPayloads {
+				err := json.Unmarshal([]byte(payload), &Link{})
+				Expect(err).To(HaveOccurred())
+				Expect(err.Error()).To(Equal("expected a JSON encoded string or object"))
+			}
+		})
+	})
 })

jsonapi/fixtures_test.go

@@ -440,6 +440,32 @@ func (i PrefixServerInformation) GetPrefix() string {
 	return prefix
 }
 
+type CustomLinksPost struct{}
+
+func (n CustomLinksPost) GetID() string {
+	return "someID"
+}
+
+func (n *CustomLinksPost) SetID(ID string) error {
+	return nil
+}
+
+func (n CustomLinksPost) GetName() string {
+	return "posts"
+}
+
+func (n CustomLinksPost) GetCustomLinks(base string) Links {
+	return Links{
+		"someLink": Link{Href: base + `/someLink`},
+		"otherLink": Link{
+			Href: base + `/otherLink`,
+			Meta: map[string]interface{}{
+				"method": "GET",
+			},
+		},
+	}
+}
+
 type NoRelationshipPosts struct{}
 
 func (n NoRelationshipPosts) GetID() string {

jsonapi/marshal.go

@@ -73,6 +73,13 @@ type MarshalIncludedRelations interface {
 	GetReferencedStructs() []MarshalIdentifier
 }
 
+// The MarshalCustomLinks interface can be implemented if the struct should
+// want any custom links.
+type MarshalCustomLinks interface {
+	MarshalIdentifier
+	GetCustomLinks(string) Links
+}
+
 // A ServerInformation implementor can be passed to MarshalWithURLs to generate
 // the `self` and `related` urls inside `links`.
 type ServerInformation interface {
@@ -204,6 +211,20 @@ func marshalData(element MarshalIdentifier, data *Data, information ServerInform
 	data.ID = element.GetID()
 	data.Type = getStructType(element)
 
+	if information != nil {
+		if customLinks, ok := element.(MarshalCustomLinks); ok {
+			if data.Links == nil {
+				data.Links = make(Links)
+			}
+			base := getLinkBaseURL(element, information)
+			for k, v := range customLinks.GetCustomLinks(base) {
+				if _, ok := data.Links[k]; !ok {
+					data.Links[k] = v
+				}
+			}
+		}
+	}
+
 	if references, ok := element.(MarshalLinkedRelations); ok {
 		data.Relationships = getStructRelationships(references, information)
 	}
@@ -297,23 +318,28 @@ func getStructRelationships(relationer MarshalLinkedRelations, information Serve
 	return relationships
 }
 
-func getLinksForServerInformation(relationer MarshalLinkedRelations, name string, information ServerInformation) *Links {
-	if information == nil {
-		return nil
-	}
-
-	links := &Links{}
-
+func getLinkBaseURL(element MarshalIdentifier, information ServerInformation) string {
 	prefix := strings.Trim(information.GetBaseURL(), "/")
 	namespace := strings.Trim(information.GetPrefix(), "/")
-	structType := getStructType(relationer)
+	structType := getStructType(element)
 
 	if namespace != "" {
 		prefix += "/" + namespace
 	}
 
-	links.Self = fmt.Sprintf("%s/%s/%s/relationships/%s", prefix, structType, relationer.GetID(), name)
-	links.Related = fmt.Sprintf("%s/%s/%s/%s", prefix, structType, relationer.GetID(), name)
+	return fmt.Sprintf("%s/%s/%s", prefix, structType, element.GetID())
+}
+
+func getLinksForServerInformation(relationer MarshalLinkedRelations, name string, information ServerInformation) Links {
+	if information == nil {
+		return nil
+	}
+
+	links := make(Links)
+	base := getLinkBaseURL(relationer, information)
+
+	links["self"] = Link{Href: fmt.Sprintf("%s/relationships/%s", base, name)}
+	links["related"] = Link{Href: fmt.Sprintf("%s/%s", base, name)}
 
 	return links
 }