PrxAccess
Elixir client library for accessing PRX HAL APIs.
Installation
Add the package to your list of dependencies in mix.exs
:
def deps do
[
{:prx_access, "~> 0.1.0"}
]
end
Usage
To make requests against the a PRX API host, just provide the hostname and start navigating:
{:ok, root} = PrxAccess.root("feeder.prx.org")
# list link rels on this root document
{:ok, rels} = PrxAccess.rels(root)
# follow one of them!
{:ok, podcasts} = PrxAccess.follow(root, "prx:podcasts", page: 1, per: 1)
IO.puts(podcasts.attributes["count"])
IO.puts(podcasts.attributes["total"])
# get items from this page
{:ok, items} = PrxAccess.follow(podcasts, "prx:items")
Enum.each(items, fn(i) -> IO.puts(i.attributes["title"]) end)
# follow off an item - woh, we're in CMS now!
{:ok, account} = hd(items) |> PrxAccess.follow("prx:account")
IO.puts(podcasts._url) # https://feeder.prx.org/api/v1/podcasts?page=1&per=1
IO.puts(account._url) # https://cms.prx.org/api/v1/accounts/5678
Authorization
To make an authorized request, you'll need a PRX client_id and client_secret for id.prx.org.
auth_options = [
account: 1234,
id_host: "id.staging.prx.tech",
client_id: "my-client-id",
client_secret: "my-client-secret"
]
{:ok, root} = PrxAccess.root("cms.staging.prx.tech", auth_options)
# or maybe you want the /api/v1/authorization entry point
{:ok, auth_root} = PrxAccess.follow("/api/v1/authorization")
# or go directly there
{:ok, auth_direct} = PrxAccess.get("https://cms.staging.prx.tech/api/v1/authorization", auth_options)
Chaining Requests
It's easy to chain together a bunch of HAL links, using elixir pipes. If any of
your resources return a non-200, you'll get a %PrxAccess.Error{}
returned for
any subsequent link-follows:
{:ok, podcast} = PrxAccess.root("feeder.prx.org")
|> PrxAccess.follow("prx:podcast", id: 70)
# or an error
{:error, err} = PrxAccess.root("feeder.prx.org")
|> PrxAccess.follow("prx:podcast", id: 70)
|> PrxAccess.follow("prx:whatev")
|> PrxAccess.follow("prx:these")
|> PrxAccess.follow("prx:arenot")
|> PrxAccess.follow("prx:called")
IO.inspect(err)
# %PrxAccess.Error{
# status: 200,
# url: "https://feeder.prx.org/api/v1/podcasts/70",
# message: "rel prx:whatev not found"
# }
License
Contributing
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request