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.2.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: "optional account_id for restricted token",
  scope: "optional scope for restricted token",
  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

MIT License

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request