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

EmbedSetter is the interface that wraps the basic setEmbedded 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
}

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

type Hal

type Hal struct {
	Links    map[string]*Link    `json:"_links,omitempty"`
	Embedded map[string]Embedded `json:"_embedded,omitempty"`
}

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

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"`
	Title string `json:"title,omitempty"`
}

Link represents a link in "_links" object