jsonhal

README

jsonhal

A simple Go package to make custom structs marshal into HAL compatible JSON responses.

---

Just add jsonhal.Hal as anonymous field to your structs and use SetLink to set hyperlinks and optionally SetEmbedded to set embedded resources.

Example:

package main

import (
	"encoding/json"
	"log"

	"github.com/RichardKnop/jsonhal"
)

// HelloWorld ...
type HelloWorld struct {
	jsonhal.Hal
	ID   uint   `json:"id"`
	Name string `json:"name"`
}

// Foobar ...
type Foobar struct {
	jsonhal.Hal
	ID   uint   `json:"id"`
	Name string `json:"name"`
}

func main() {
	var (
		helloWorld   *HelloWorld
		jsonResponse []byte
		err          error
	)

	helloWorld = &HelloWorld{ID: 1, Name: "Hello World"}
	helloWorld.SetLink("self", "/v1/hello/world/1", "")

	jsonResponse, err = json.Marshal(helloWorld)
	if err != nil {
		log.Fatal(err)
	}
	log.Print(string(jsonResponse))
	// {
	// 	"_links": {
	// 		"self": {
	// 			"href": "/v1/hello/world/1"
	// 		}
	// 	},
	// 	"id": 1,
	// 	"name": "Hello World"
	// }

	helloWorld = &HelloWorld{ID: 1, Name: "Hello World"}
	helloWorld.SetLink(
		"self", // name
		"/v1/hello/world?offset=2&limit=2", // href
		"", // title
	)
	helloWorld.SetLink(
		"next", // name
		"/v1/hello/world?offset=4&limit=2", // href
		"", // title
	)
	helloWorld.SetLink(
		"previous",                         // name
		"/v1/hello/world?offset=0&limit=2", // href
		"", // title
	)
	jsonResponse, err = json.Marshal(helloWorld)
	if err != nil {
		log.Fatal(err)
	}
	log.Print(string(jsonResponse))
	// {
	// 	"_links": {
	// 		"next": {
	// 			"href": "/v1/hello/world?offset=4\u0026limit=2"
	// 		},
	// 		"previous": {
	// 			"href": "/v1/hello/world?offset=0\u0026limit=2"
	// 		},
	// 		"self": {
	// 			"href": "/v1/hello/world?offset=2\u0026limit=2"
	// 		}
	// 	},
	// 	"id": 1,
	// 	"name": "Hello World"
	// }

	helloWorld = &HelloWorld{ID: 1, Name: "Hello World"}
	helloWorld.SetLink("self", "/v1/hello/world/1", "")

	// Add embedded resources
	foobars := []*Foobar{
		&Foobar{
			Hal: jsonhal.Hal{
				Links: map[string]*jsonhal.Link{
					"self": &jsonhal.Link{Href: "/v1/foo/bar/1"},
				},
			},
			ID:   1,
			Name: "Foo bar 1",
		},
		&Foobar{
			Hal: jsonhal.Hal{
				Links: map[string]*jsonhal.Link{
					"self": &jsonhal.Link{Href: "/v1/foo/bar/2"},
				},
			},
			ID:   2,
			Name: "Foo bar 2",
		},
	}
	helloWorld.SetEmbedded("foobars", Embedded(foobars))

	jsonResponse, err = json.Marshal(helloWorld)
	if err != nil {
		log.Fatal(err)
	}
	log.Print(string(jsonResponse))
	// {
	// 	"_links": {
	// 		"self": {
	// 			"href": "/v1/hello/world/1"
	// 		}
	// 	},
	// 	"_embedded": {
	// 		"foobars": [
	// 			{
	// 				"_links": {
	// 					"self": {
	// 						"href": "/v1/foo/bar/1"
	// 					}
	// 				},
	// 				"id": 1,
	// 				"name": "Foo bar 1"
	// 			},
	// 			{
	// 				"_links": {
	// 					"self": {
	// 						"href": "/v1/foo/bar/2"
	// 					}
	// 				},
	// 				"id": 2,
	// 				"name": "Foo bar 2"
	// 			}
	// 		]
	// 	},
	// 	"id": 1,
	// 	"name": "Hello World"
	// }
}

Documentation

Overview

Package jsonhal provides structs and methods to easily wrap your own data in a HAL compatible struct with support for hyperlinks and embedded resources HAL specification: http://stateless.co/hal_specification.html

Index

• type EmbedGetter
• type EmbedSetter
• type Embedded
• type Embedder
• type Hal
  • func (h *Hal) CountEmbedded(name string) (int, error)
  • func (h *Hal) DecodeEmbedded(name string, result interface{}) (err error)
  • func (h *Hal) DeleteEmbedded(name string)
  • func (h *Hal) DeleteLink(name string)
  • func (h *Hal) GetEmbedded(name string) (Embedded, error)
  • func (h *Hal) GetLink(name string) (*Link, error)
  • func (h *Hal) SetEmbedded(name string, embedded Embedded)
  • func (h *Hal) SetLink(name, href, title string)
• type Link

Types

type EmbedGetter

type EmbedGetter interface {
	GetEmbedded(name string) (Embedded, error)
}

EmbedGetter is the interface that wraps the basic getEmbedded method.

GetEmbedded returns a slice of embedded resources by name or error

type EmbedSetter

type EmbedSetter interface {
	SetEmbedded(name string, embedded Embedded)
}

EmbedSetter is the interface that wraps the basic setEmbedded method.

SetEmbedded adds a slice of objects under a named key in the embedded map

type Embedded

type Embedded interface{}

Embedded represents a resource in "_embedded" object

type Embedder

type Embedder interface {
	EmbedSetter
	EmbedGetter
}

Embedder is the interface that wraps the basic setEmbedded and getEmbedded methods.

type Hal

type Hal struct {
	Links    map[string]*Link    `json:"_links,omitempty" mapstructure:"_links"`
	Embedded map[string]Embedded `json:"_embedded,omitempty" mapstructure:"_embedded"`
	// contains filtered or unexported fields
}

Hal is used for composition, include it as anonymous field in your structs

func (*Hal) CountEmbedded

func (h *Hal) CountEmbedded(name string) (int, error)

CountEmbedded counts number of embedded items

func (*Hal) DecodeEmbedded

func (h *Hal) DecodeEmbedded(name string, result interface{}) (err error)

DecodeEmbedded decodes embedded objects into a struct

func (*Hal) DeleteEmbedded

func (h *Hal) DeleteEmbedded(name string)

DeleteEmbedded removes an embedded resource named name if it is found

func (*Hal) DeleteLink

func (h *Hal) DeleteLink(name string)

DeleteLink removes a link named name if it is found

func (*Hal) GetEmbedded

func (h *Hal) GetEmbedded(name string) (Embedded, error)

GetEmbedded returns a slice of embedded resources by name or error

func (*Hal) GetLink

func (h *Hal) GetLink(name string) (*Link, error)

GetLink returns a link by name or error

func (*Hal) SetEmbedded

func (h *Hal) SetEmbedded(name string, embedded Embedded)

SetEmbedded adds a slice of objects under a named key in the embedded map

func (*Hal) SetLink

func (h *Hal) SetLink(name, href, title string)

SetLink sets a link (self, next, etc). Title argument is optional

type Link

type Link struct {
	Href  string `json:"href" mapstructure:"href"`
	Title string `json:"title,omitempty" mapstructure:"title"`
}

Link represents a link in "_links" object