ExDisco (ex_disco v0.1.0)

Elixir client for the Discogs API.

Discogs is the world's largest crowdsourced music database. ExDisco provides a type-safe, ergonomic Elixir interface to query artists, releases, labels, and users, with support for both personal token and OAuth 1.0a authentication.

Getting Started

Start by configuring a user-agent (required by Discogs):

config :ex_disco, ExDisco,
  user_agent: "my_app/1.0.0 (+https://github.com/me/my_app)"

Then fetch data:

{:ok, artist} = ExDisco.Artists.get(1)
IO.inspect(artist.name)

See the resource modules for specific data types:

• ExDisco.Artists — Query artists
• ExDisco.Releases — Query releases (albums, EPs, etc.)
• ExDisco.Labels — Query record labels
• ExDisco.Users — Query user profiles
• ExDisco.Search — Global search

Configuration

Required: User Agent

Discogs requires all applications identify themselves with a user agent:

config :ex_disco, ExDisco,
  user_agent: "my_app/1.0.0 (+https://github.com/me/my_app)"

Optional: Authentication

Choose one of two approaches:

Personal Token (Simple)

For personal scripts, CLIs, and single-user applications. Get a token at https://www.discogs.com/settings/developers, then configure it:

config :ex_disco, ExDisco,
  user_token: "your_token"

Use it in requests:

token = ExDisco.Auth.user_token("your_token")
Request.get("/users/me")
|> Request.put_auth(token)
|> Request.execute(&User.Identity.from_api/1)

OAuth 1.0a (Multi-User)

For applications acting on behalf of multiple users. Register your app at https://www.discogs.com/settings/developers to obtain consumer credentials:

config :ex_disco, ExDisco,
  consumer_key: "your_consumer_key",
  consumer_secret: "your_consumer_secret"

Each user goes through the OAuth flow to obtain their own access token and secret. Store these per-user and pass them to authenticated requests:

credentials = ExDisco.Auth.oauth_credentials(
  consumer_key,
  consumer_secret,
  user.discogs_token,
  user.discogs_token_secret
)

Request.get("/users/me")
|> Request.put_auth(credentials)
|> Request.execute(&User.Identity.from_api/1)

See ExDisco.Auth for the complete OAuth flow documentation.

Examples

Fetch an artist:

{:ok, artist} = ExDisco.Artists.get(1)

Fetch release information:

{:ok, release} = ExDisco.Releases.get_release(249504)

Search the database:

{:ok, page} = ExDisco.Search.query([q: "Thriller", type: :release])
IO.inspect(page.items)

Handle errors:

case ExDisco.Artists.get(9999999) do
  {:ok, artist} -> IO.inspect(artist)
  {:error, error} -> IO.inspect("Error: #{error.message}")
end

See the request builder for advanced usage:

{:ok, releases} = ExDisco.Request.get("/artists/1/releases")
|> ExDisco.Request.put_query(per_page: 25)
|> ExDisco.Request.execute_collection("releases", &ReleaseSummary.from_api/1)