Templated Links
One of the features of HAL is the ability to use templated links. These are links whose href has one or more placeholders that you can fill in with values. For example, an orders collection resource may have the following links:
json
{
"_links": {
"self": {
"href": "/orders"
},
"item": {
"href": "/orders/{order_number}",
"templated": true
}
}
}With halchemy you supply values for the template placeholders using with template values:
If you do not supply a value for a template placeholder, the placeholder is simply removed.
The syntax for templated links is specified in RFC 6570 and is very expressive. Here are some sample templates, and what the URL looks like when filled with these values:
| Templated URL | Values | Resulting URL |
/path/{foo} | {"foo":"321"} | /path/321 |
/has/{foo}/multiples/{bar} | {
"foo":"value",
"bar":"value"
} | /has/value/multiples/value |
/orders{?id} | {"id":"123"} | /orders?id=123 |
/search{?query,type} | {
"query":"hal",
"type":"specification"
} | /search?query=hal&type=specification |
/items/{itemId}{?lang,format} | {
"itemId":"42",
"lang":"en",
"format":"json"
} | /items/42?lang=en&format=json |
/country/{countryCode}/cities{?page,limit} | {
"countryCode":"US",
"page":"1",
"limit":"10"
} | /country/US/cities?page=1&limit=10 |
/profile/{userId}{?fields} | {
"userId":"789",
"fields":"name,age"
} | /profile/789?fields=name%2Cage |
/search{?keys*} | {
"keys": {
"role": "admin",
"status": "active"
}
} | /search?role=admin&status=active |
/find{#section} | {"section":"results"} | /find#results |
/browse/{.format} | {"format":"json"} | /browse/.json |
/location/{country}/{city}/{?coords*} | {
"country":"Canada",
"city":"Toronto",
"coords": {
"lat":43.7,
"long":-79.42
}
} | /location/Canada/Toronto/?lat=43.7&long=-79.42 |
/files{/year,month,day,filename} | {
"year":"2023",
"month":"04",
"day":"01",
"filename":"report.pdf"
} | /files/2023/04/01/report.pdf |
/tags{?list*} | {
"list":[
"api",
"hal",
"rfc6570"
]
} | /tags?list=api&list=hal&list=rfc6570 |
/users/{userId}/posts{/postId}{?comments} | {
"userId":"100",
"postId":"200",
"comments":"all"
} | /users/100/posts/200?comments=all |
/path?fixedParam=value{&foo} | {"foo":"bar"} | /path?fixedParam=value&foo=bar |