From eb9912d3d53d07715f1b0a5475a867117fa82856 Mon Sep 17 00:00:00 2001 From: Jason Cummings Date: Tue, 2 Aug 2016 21:03:24 -0400 Subject: [PATCH] Tweaks for version 1.0.0 release --- README.md | 42 ++++++++++++++++++----------- lib/spotify/album.ex | 3 ++- lib/spotify/categories.ex | 57 ++++++++++++++++++++++++++++++++------- mix.exs | 2 +- test/doc_test.exs | 2 ++ 5 files changed, 79 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index c6d43a2..fb28512 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ 1. Add spotify_ex to your list of dependencies in `mix.exs`: def deps do - [{:spotify_ex, "~> 0.1.4"}] + [{:spotify_ex, "~> 1.0.0"}] end 2. Ensure spotify_ex is started before your application: @@ -19,24 +19,29 @@ [applications: [:spotify_ex]] end -## This package is under active development and will change frequently. -APIs covered so far: -- OAuth -- Playlists -- Personalization -- Profile -- Albums -- Tracks -- Artists - -APIs In Progress: -- Browse -- Follow -- Library [Documentation](https://hexdocs.pm/spotify_ex/0.1.3/api-reference.html) -Breaking changes will occur until 1.0! +## What does this wrapper cover? + +This wrapper covers the [Spotify Web +API](https://developer.spotify.com/web-api/endpoint-reference/). + +Follow that link, on the left you'll notice they have the API broken into +sections, such as Artists, Albums, Playlists, etc. This wrapper does its best +to keep endpoints in modules mapped to their corresponding section, however +Spotify duplicates many of its endpoints. For example, there's an endpoint to +get an artist's albums that's listed under both Artists and Albums. The endpoints +are not duplicated in this wrapper, so if you don't see an endpoint, it's a +module that's also related to that endpoint i.e, if you don't see that endpoint +in the `Artist` module, check `Albums`. + +Example: All of the endpoints in the "Follow" section are in other modules, but +they're all about following Playlists, Artists, etc. The `follow_playlist` +endpoint will be in the `Playlist` module. + +These duplicate endpoints may get aliased in the future to have a 1-1 mapping +with the docs. ## Usage @@ -150,3 +155,8 @@ end The authentication module will set refresh and access tokens in a cookie. The access token expires every hour, and you'll need to check your reponses for 401 errors. Call `Spotify.Authentication.refresh`, if there is a refresh token present. If not, you'll need to redirect back to authorization. +## Contributing + +All contributions are more than Welcome! I will not accept a PR without tests if it +looks like something that should be tested, which is pretty much everything. +All public API must be documented. diff --git a/lib/spotify/album.ex b/lib/spotify/album.ex index 4f231be..f122b48 100644 --- a/lib/spotify/album.ex +++ b/lib/spotify/album.ex @@ -96,7 +96,8 @@ defmodule Spotify.Album do end @doc""" - Foo + Get Spotify catalog information about an album’s tracks. + iex> Spotify.Album.get_album_tracks_url("4") "https://api.spotify.com/v1/albums/4/tracks" """ diff --git a/lib/spotify/categories.ex b/lib/spotify/categories.ex index 15c7cf0..4fb3d3b 100644 --- a/lib/spotify/categories.ex +++ b/lib/spotify/categories.ex @@ -4,34 +4,73 @@ defmodule Spotify.Category do use Responder @behaviour Responder import Helpers - alias Spotify.{Category, Client} + alias Spotify.{Category, Client, Seed} defstruct ~w[href icons id name]a - def get_categories do + @doc """ + Get a list of categories used to tag items in Spotify + [Spotify Documentation](https://developer.spotify.com/web-api/get-list-categories/) - end + **Method**: `GET` - def get_categories_url do + **Optional Params**: `country`, `locale`, `limit`, `offset` + Spotify.Category.get_categories(conn, params) + # => { :ok, %Paging{items: [%Category{}, ...]} } + """ + def get_categories(conn, params \\ []) do + url = get_categories_url(params) + conn |> Client.get(url) |> handle_response end - def get_category do + @doc """ + Get a list of categories used to tag items in Spotify + iex> Spotify.Category.get_categories_url(country: "US") + "https://api.spotify.com/v1/browse/categories?country=US" + """ + def get_categories_url(params \\ []) do + "https://api.spotify.com/v1/browse/categories" <> query_string(params) end - def get_category_url do - end + @doc """ + Get a single category used to tag items in Spotify + [Spotify Documentation](https://developer.spotify.com/web-api/get-category/) + + **Method**: `GET` - def get_recommendations do + **Optional Params**: `country`, `locale` + Spotify.Category.get_category(conn, id) + # => {:ok, %Category{}} + """ + def get_category(conn, id, params \\ []) do + url = get_category_url(id, params) + conn |> Client.get(url) |> handle_response end - def get_recommendations_url do + @doc """ + Get a single category used to tag items in Spotify + + iex> Spotify.Category.get_category_url("4") + "https://api.spotify.com/v1/browse/categories/4" + """ + def get_category_url(id, params \\ []) do + "https://api.spotify.com/v1/browse/categories/#{id}" <> query_string(params) end + def build_response(body) do + case body do + %{ "categories" => categories } -> build_categories(body, categories["items"]) + category -> to_struct(Category, category) + end + end + def build_categories(body, categories) do + categories = Enum.map(categories, &to_struct(Category, &1)) + Paging.response(body, categories) end end diff --git a/mix.exs b/mix.exs index 9914c26..e20a84e 100644 --- a/mix.exs +++ b/mix.exs @@ -3,7 +3,7 @@ defmodule Spotify.Mixfile do def project do [app: :spotify_ex, - version: "0.1.4", + version: "1.0.0", elixir: "~> 1.3", description: description, package: package, diff --git a/test/doc_test.exs b/test/doc_test.exs index 425bf11..ff47b4b 100644 --- a/test/doc_test.exs +++ b/test/doc_test.exs @@ -3,7 +3,9 @@ defmodule DocTest do doctest Spotify.Album doctest Spotify.Artist + doctest Spotify.Category doctest Spotify.Personalization + doctest Spotify.Recommendation doctest Spotify.Playlist doctest Spotify.Profile doctest Spotify.Search