Formed in 2009, the Archive Team (not to be confused with the archive.org Archive-It Team) is a rogue archivist collective dedicated to saving copies of rapidly dying or deleted websites for the sake of history and digital heritage. The group is 100% composed of volunteers and interested parties, and has expanded into a large amount of related projects for saving online and digital history.
Hal
Go implementation of the HAL standard.
This is a work in progress... Everything might/will change.
Usage
The library gives a way of mapping Go Structs into HAL Resources by implementing the hal.Mapper interface. You only need to define which fields you want and how you want them translated.
type Mapper interface {
GetMap() Entry
}For a given Product struct, this would be the hal.Mapper implementation:
type Product struct {
Code int
Name string
Price int
}
func (p Product) GetMap() hal.Entry {
return hal.Entry{
"name": p.Name,
"price": p.Price,
}
}Then you can just create a HAL Resource for a Product by:
p := Product{
Code: 1,
Name: "Some Product",
Price: 10
}
pr := hal.NewResource(p, "http://rest.api/products/1")And pass it through json.Marsal when needed getting this result:
{
"_links": {
"self": {"href": "http://rest.api/products/1"}
},
"name": "Some product",
"price": 10
}Embedded Resources
Let's say your API has to serve a list of Task structs.
Since for HAL standard everything is a resource, even the entire API response could be seen as a resource containing other embedded resources. Check this out:
type (
Response struct {
Count int
Total int
}
Task struct {
Id int
Name string
}
)
func (p Response) GetMap() hal.Entry {
return hal.Entry{
"count": p.Count,
"total": p.Total,
}
}
func (c Task) GetMap() hal.Entry {
return hal.Entry{
"id": c.Id,
"name": c.Name,
}
}Then you could create the Resources by doing something like this:
// Creating Response resource
r := hal.NewResource(Response{Count: 10, Total: 20}, "/tasks")
r.AddNewLink("next", "/tasks=page=2")
// Creating Task resources
t1 := hal.NewResource(Task{Id: 1, Name: "Some Task"}, "/tasks/1")
t2 := hal.NewResource(Task{Id: 2, Name: "Some Task"}, "/tasks/2")
// Embedding
r.Embed("tasks", t1)
r.Embed("tasks", t2)Output:
{
"_embedded": {
"tasks": [
{
"_links": {
"self": {
"href": "/tasks/1"
}
},
"id": 1,
"name": "Some Task"
},
{
"_links": {
"self": {
"href": "/tasks/2"
}
},
"id": 2,
"name": "Some Task"
}
]
},
"_links": {
"next": {
"href": "/tasks=page=2"
},
"self": {
"href": "/tasks"
}
},
"count": 10,
"total": 20
}CURIES
To include CURIE relations in your output you can 'register' the curie name and fluently add a link relation as follows:
p := Product{
Code: 1,
Name: "Some Product",
Price: 10
}
// Creating Product resource
pr := hal.NewResource(p, "http://rest.api/products/1")
pr.RegisterCurie("acme", "http://acme.com/docs/{rel}", true).AddNewLink("widgets", "http://rest.api/products/1/widgets")Output
{
"_links": {
"self": {"href": "http://rest.api/products/1"},
"curies": [{
"name":"acme",
"href":"http://acme.com/docs/{rel}",
"templated":true
}],
"acme:widgets": { "href": "http://rest.api/products/1/widgets" }
},
"name": "Some product",
"price": 10
}Registered curies can also be retreived by name from the resources' Curies map:
pr := hal.NewResource(p, "http://rest.api/products/1")
pr.RegisterCurie("acme", "http://acme.com/docs/{rel}", true)
...
curie := pr.Curies["acme"]
curie.AddNewLink("widgets", "http://rest.api/products/1/widgets")Todo
- XML Marshaler.