exhal v2.2.0 ExHal
Use HAL APIs with ease.
Example
iex> doc = ExHal.parse(~s|
...> { "name": "Hello!",
...> "_links": {
...> "self" : { "href": "http://example.com" },
...> "profile": [{ "href": "http://example.com/special" },
...> { "href": "http://example.com/normal" }]
...> }
...> }
...> |)
%ExHal.Document{headers: [], links: %{"profile" => [%ExHal.Link{name: nil, rel: "profile", target: nil,
href: "http://example.com/normal", templated: false},
%ExHal.Link{name: nil, rel: "profile", target: nil, href: "http://example.com/special",
templated: false}],
"self" => [%ExHal.Link{name: nil, rel: "self", target: nil, href: "http://example.com",
templated: false}]}, properties: %{"name" => "Hello!"}}
iex> ExHal.url(doc)
{:ok, "http://example.com"}
iex> ExHal.fetch(doc, "name")
{:ok, "Hello!"}
iex> ExHal.fetch(doc, "non-existent")
:error
iex> ExHal.fetch(doc, "profile")
{:ok,
[%ExHal.Link{name: nil, rel: "profile", target: nil,
href: "http://example.com/normal",
templated: false},
%ExHal.Link{name: nil, rel: "profile", target: nil,
href: "http://example.com/special",
templated: false}]}
iex> ExHal.get_links_lazy(doc, "profile", fn -> [] end)
[%ExHal.Link{name: nil, rel: "profile", target: nil,
href: "http://example.com/normal",
templated: false},
%ExHal.Link{name: nil, rel: "profile", target: nil,
href: "http://example.com/special",
templated: false}]
iex> ExHal.get_links_lazy(doc, "alternate", fn -> [] end)
[]
ExHal can also make requests. Continuing the example above:
ExHal.follow_link(doc, "profile")
{:error, %ExHal.Error{reason: "multiple choices"}}
ExHal.follow_link(doc, "nonexistent")
{:error, %ExHal.Error{reason: "no such link"}}
ExHal.follow_link("self")
{:ok, %ExHal.Document{...}}
ExHal.follow_link(doc, "profile", pick_volunteer: true)
{:ok, %ExHal.Document{...}}
ExHal.follow_links(doc, "profile")
[{:ok, %ExHal.Document{...}}, {:ok, %ExHal.Document{...}}]
ExHal.follow_links(doc, "profile", headers: ["Content-Type": "application/vnd.custom.json+type"])
[{:ok, %ExHal.Document{...}}, {:ok, %ExHal.Document{...}}]
ExHal.post(doc, "self", ~s|
...> { "name": "http://example.com/new-thing",
...> "_links": {
...> "self": { "href": "http://example.com/new-thing" }
...> }
...> }
...> |)
{:ok, %ExHal.Document{...}}
Summary
Functions
Fetches value of specified property or links whose rel
matches
Follows a link in a HAL document
Follows all links of a particular rel in a HAL document
Returns link or property of the specified name, or the result of default_fun
if neither are found
Returns [%Link{}...]
when link exists
result of `default_fun` otherwise
Returns <property value>
when property exists
result of `default_fun` otherwise
Returns a new %ExHal.Document
representing the HAL document provided
Posts data to the named link in a HAL document
Returns {:ok, <url of specified document>}
`:error`
Functions
Fetches value of specified property or links whose rel
matches
Returns {:ok, <property value>}
if name
identifies a property;
`{:ok, [%Link{}, ...]}` if `name` identifies a link;
`:error` othewise
Follows a link in a HAL document.
Returns {:ok, %ExHal.Document{...}}
if request is an error
`{:error, %ExHal.Error{...}}` if not
Follows all links of a particular rel in a HAL document.
Returns [{:ok, %ExHal.Document{...}}, {:error, %ExHal.Error{...}, ...]
Returns link or property of the specified name, or the result of default_fun
if neither are found.
Returns [%Link{}...]
when link exists
result of `default_fun` otherwise
Returns <property value>
when property exists
result of `default_fun` otherwise
Posts data to the named link in a HAL document.
Returns {:error, %ExHal.Error{...}}
if request is an error
`{:ok, %ExHal.Document{...}}` if not