Update README for 1.0 & add migration instructions

yammine · Sep 20, 2016 · d3f8b52 · d3f8b52
1 parent f987bb3
commit d3f8b52
Show file tree

Hide file tree

Showing 4 changed files with 62 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -4,6 +4,34 @@ A library for interfacing with the Trello API.
 
 Heavily influenced by https://github.com/parroty/extwitter with some stuff straight ripped out of it.
 
+## **Important! Migration from 0.x -> 1.x**
+Since this change will break all existing projects using ExTrello upon upgrading this deserves a spot at the top :)
+
+All calls to the Trello API will now be wrapped in a tuple with the first element either being `:ok`, `:error`, or `:connection_error`
+Regular errors will no longer raise exceptions as that is not idiomatic.
+
+Here's an example(just a little sample):
+```elixir
+# Old and bad
+boards = ExTrello.boards()
+# New and great
+{:ok, boards} = ExTrello.boards()
+
+# Old and bad, yuck!
+try do
+  ExTrello.get("potato/2")
+rescue
+  %ExTrello.Error{code: code, message: message} -> IO.puts "ERROR[#{code}] - #{message}"
+end
+
+# New and fantastic
+case ExTrello.get("potato/2") do
+  {:ok, response} -> response
+  {:error, code, message} -> IO.puts "ERROR[#{code}] - #{message}"
+  {:connection_error, _reason, _message} -> IO.puts "Connection error, will try again later."
+end
+```
+
 ## Documentation
 - https://hexdocs.pm/ex_trello
 
@@ -17,7 +45,7 @@ Heavily influenced by https://github.com/parroty/extwitter with some stuff strai
     def deps do
       [
         ...,
-        {:ex_trello, "~> 0.5.0"}
+        {:ex_trello, "~> 1.0.0"}
       ]
     end
     ```

diff --git a/lib/ex_trello.ex b/lib/ex_trello.ex
@@ -68,7 +68,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username
   """
-  @spec member() :: ExTrello.Model.Member.t
+  @spec member() :: {:ok, ExTrello.Model.Member.t}
   defdelegate member, to: ExTrello.API.Members
 
   @doc """
@@ -81,7 +81,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username
   """
-  @spec member(Keyword.t) :: ExTrello.Model.Member.t
+  @spec member(Keyword.t) :: {:ok, ExTrello.Model.Member.t}
   defdelegate member(options), to: ExTrello.API.Members
 
   @doc """
@@ -91,7 +91,7 @@ defmodule ExTrello do
 
       {:ok, boards} = ExTrello.boards()
   """
-  @spec boards() :: [ExTrello.Model.Board.t]
+  @spec boards() :: {:ok, [ExTrello.Model.Board.t]}
   defdelegate boards, to: ExTrello.API.Boards
 
   @doc """
@@ -104,7 +104,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-boards
   """
-  @spec boards(Keyword.t) :: [ExTrello.Model.Board.t]
+  @spec boards(Keyword.t) :: {:ok, [ExTrello.Model.Board.t]}
   defdelegate boards(options), to: ExTrello.API.Boards
 
 
@@ -118,7 +118,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/member#get-1-members-idmember-or-username-boards
   """
-  @spec boards(String.t, Keyword.t) :: [ExTrello.Model.Board.t]
+  @spec boards(String.t, Keyword.t) :: {:ok, [ExTrello.Model.Board.t]}
   defdelegate boards(user, options), to: ExTrello.API.Boards
 
   @doc """
@@ -131,7 +131,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/board#get-1-boards-board-id
   """
-  @spec board(String.t) :: ExTrello.Model.Board.t
+  @spec board(String.t) :: {:ok, ExTrello.Model.Board.t}
   defdelegate board(id), to: ExTrello.API.Boards
 
   @doc """
@@ -149,7 +149,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/board#get-1-boards-board-id
   """
 
-  @spec board(String.t, Keyword.t) :: ExTrello.Model.Board.t
+  @spec board(String.t, Keyword.t) :: {:ok, ExTrello.Model.Board.t}
   defdelegate board(id, options), to: ExTrello.API.Boards
 
   @doc """
@@ -164,7 +164,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/board#post-1-boards
   """
 
-  @spec create_board(String.t) :: ExTrello.Model.Board.t
+  @spec create_board(String.t) :: {:ok, ExTrello.Model.Board.t}
   defdelegate create_board(name), to: ExTrello.API.Boards
 
   @doc """
@@ -179,7 +179,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/board#post-1-boards
   """
 
-  @spec create_board(String.t, Keyword.t) :: ExTrello.Model.Board.t
+  @spec create_board(String.t, Keyword.t) :: {:ok, ExTrello.Model.Board.t}
   defdelegate create_board(name, options), to: ExTrello.API.Boards
 
   @doc """
@@ -195,7 +195,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/board#put-1-boards-board-id
   """
 
-  @spec edit_board(String.t, Keyword.t) :: ExTrello.Model.Board.t
+  @spec edit_board(String.t, Keyword.t) :: {:ok, ExTrello.Model.Board.t}
   defdelegate edit_board(id, options), to: ExTrello.API.Boards
 
   @doc """
@@ -213,7 +213,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-cards
   """
-  @spec board_cards(String.t | ExTrello.Model.Board.t) :: [ExTrello.Model.Card.t]
+  @spec board_cards(String.t | ExTrello.Model.Board.t) :: {:ok, [ExTrello.Model.Card.t]}
   defdelegate board_cards(board_or_id), to: ExTrello.API.Boards, as: :cards
 
   @doc """
@@ -232,7 +232,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-cards
   """
 
-  @spec board_cards(String.t | ExTrello.Model.Board.t, Keyword.t) :: [ExTrello.Model.Card.t]
+  @spec board_cards(String.t | ExTrello.Model.Board.t, Keyword.t) :: {:ok, [ExTrello.Model.Card.t]}
   defdelegate board_cards(board_or_id, options), to: ExTrello.API.Boards, as: :cards
 
   @doc """
@@ -249,7 +249,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink
   """
-  @spec card(String.t) :: ExTrello.Model.Card.t
+  @spec card(String.t) :: {:ok, ExTrello.Model.Card.t}
   defdelegate card(card_id_or_shortlink), to: ExTrello.API.Cards
 
   @doc """
@@ -263,7 +263,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink
   """
 
-  @spec card(String.t, Keyword.t) :: ExTrello.Model.Card.t
+  @spec card(String.t, Keyword.t) :: {:ok, ExTrello.Model.Card.t}
   defdelegate card(card_id_or_shortlink, options), to: ExTrello.API.Cards
 
   @doc """
@@ -279,7 +279,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/card#post-1-cards
   """
 
-  @spec create_card(String.t | ExTrello.Model.List.t, String.t) :: ExTrello.Model.Card.t
+  @spec create_card(String.t | ExTrello.Model.List.t, String.t) :: {:ok, ExTrello.Model.Card.t}
   defdelegate create_card(list_or_id, name), to: ExTrello.API.Cards
 
   @doc """
@@ -297,7 +297,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/card#post-1-cards
   """
 
-  @spec create_card(String.t | ExTrello.Model.List.t, String.t, Keyword.t) :: ExTrello.Model.Card.t
+  @spec create_card(String.t | ExTrello.Model.List.t, String.t, Keyword.t) :: {:ok, ExTrello.Model.Card.t}
   defdelegate create_card(list_or_id, name, options), to: ExTrello.API.Cards
 
   @doc """
@@ -320,7 +320,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink
   """
 
-  @spec edit_card(String.t | ExTrello.Model.Card.t, Keyword.t) :: ExTrello.Model.Card.t
+  @spec edit_card(String.t | ExTrello.Model.Card.t, Keyword.t) :: {:ok, ExTrello.Model.Card.t}
   defdelegate edit_card(card_or_id_or_shortlink, properties_to_edit), to: ExTrello.API.Cards
 
   @doc """
@@ -333,7 +333,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-actions-comments
   """
-  @spec create_comment(String.t | ExTrello.Model.Card.t, String.t) :: ExTrello.Model.Action.t
+  @spec create_comment(String.t | ExTrello.Model.Card.t, String.t) :: {:ok, ExTrello.Model.Action.t}
   defdelegate create_comment(card_or_id_or_shortlink, text), to: ExTrello.API.Cards
 
   @doc """
@@ -347,7 +347,7 @@ defmodule ExTrello do
   https://developers.trello.com/advanced-reference/action#actions-idaction
   """
 
-  @spec action(String.t) :: ExTrello.Model.Action.t
+  @spec action(String.t) :: {:ok, ExTrello.Model.Action.t}
   defdelegate action(action_id), to: ExTrello.API.Actions
 
   @doc """
@@ -364,7 +364,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/list#get-1-lists-idlist
   """
-  @spec list(String.t | ExTrello.Model.List.t) :: ExTrello.Model.List.t
+  @spec list(String.t | ExTrello.Model.List.t) :: {:ok, ExTrello.Model.List.t}
   defdelegate list(id_or_struct), to: ExTrello.API.Lists
 
   @doc """
@@ -377,7 +377,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/list#get-1-lists-idlist
   """
-  @spec list(String.t | ExTrello.Model.List.t, Keyword.t) :: ExTrello.Model.List.t
+  @spec list(String.t | ExTrello.Model.List.t, Keyword.t) :: {:ok, ExTrello.Model.List.t}
   defdelegate list(id_or_struct, options), to: ExTrello.API.Lists
 
   @doc """
@@ -397,7 +397,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/list#post-1-lists
   """
-  @spec create_list(String.t | ExTrello.Model.Board.t, String.t) :: ExTrello.Model.List.t
+  @spec create_list(String.t | ExTrello.Model.Board.t, String.t) :: {:ok, ExTrello.Model.List.t}
   defdelegate create_list(board_id_or_struct, name), to: ExTrello.API.Lists
 
   @doc """
@@ -417,7 +417,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/list#post-1-lists
   """
-  @spec create_list(String.t | ExTrello.Model.Board.t, String.t, Keyword.t) :: ExTrello.Model.List.t
+  @spec create_list(String.t | ExTrello.Model.Board.t, String.t, Keyword.t) :: {:ok, ExTrello.Model.List.t}
   defdelegate create_list(board_id_or_struct, name, options), to: ExTrello.API.Lists
 
   @doc """
@@ -436,7 +436,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/list#put-1-lists-idlist
   """
-  @spec edit_list(String.t | ExTrello.Model.List.t, Keyword.t) :: ExTrello.Model.List.t
+  @spec edit_list(String.t | ExTrello.Model.List.t, Keyword.t) :: {:ok, ExTrello.Model.List.t}
   defdelegate edit_list(list_id_or_struct, fields), to: ExTrello.API.Lists
 
   @doc """
@@ -449,7 +449,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist
   """
-  @spec checklist(String.t) :: ExTrello.Model.Checklist.t
+  @spec checklist(String.t) :: {:ok, ExTrello.Model.Checklist.t}
   defdelegate checklist(id), to: ExTrello.API.Checklists
 
   @doc """
@@ -462,7 +462,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist
   """
-  @spec checklist(String.t, Keyword.t) :: ExTrello.Model.Checklist.t
+  @spec checklist(String.t, Keyword.t) :: {:ok, ExTrello.Model.Checklist.t}
   defdelegate checklist(id, options), to: ExTrello.API.Checklists
 
   @doc """
@@ -480,7 +480,7 @@ defmodule ExTrello do
   ## Reference
   https://developers.trello.com/advanced-reference/checklist#get-1-checklists-idchecklist-board
   """
-  @spec checklist_board(String.t | ExTrello.Model.Checklist.t) :: ExTrello.Model.Board.t
+  @spec checklist_board(String.t | ExTrello.Model.Checklist.t) :: {:ok, ExTrello.Model.Board.t}
   defdelegate checklist_board(id_or_struct), to: ExTrello.API.Checklists
 
   @doc """
@@ -490,7 +490,7 @@ defmodule ExTrello do
 
       {:ok, response} = ExTrello.get("boards/57ae3940f43e6d960e0c45da/boardStars", filter: "mine")
   """
-  @spec get(String.t, Keyword.t) :: String.t
+  @spec get(String.t, Keyword.t) :: {:ok, String.t}
   defdelegate get(path, params \\ []), to: ExTrello.API.BareRequests
 
   @doc """
@@ -500,7 +500,7 @@ defmodule ExTrello do
 
       {:ok, response} = ExTrello.post("boards/57ae3940f43e6d960e0c45da/lists", name: "Best List", pos: "top")
   """
-  @spec post(String.t, Keyword.t) :: String.t
+  @spec post(String.t, Keyword.t) :: {:ok, String.t}
   defdelegate post(path, params \\ []), to: ExTrello.API.BareRequests
 
   @doc """
@@ -510,7 +510,7 @@ defmodule ExTrello do
 
       {:ok, response} = ExTrello.put("boards/57ae3940f43e6d960e0c45da/labelNames/blue", value: "Bluey")
   """
-  @spec put(String.t, Keyword.t) :: String.t
+  @spec put(String.t, Keyword.t) :: {:ok, String.t}
   defdelegate put(path, params \\ []), to: ExTrello.API.BareRequests
 
   @doc """
@@ -520,7 +520,7 @@ defmodule ExTrello do
 
       {:ok, response} = ExTrello.delete("boards/57ae3940f43e6d960e0c45da/powerUps/calendar")
   """
-  @spec delete(String.t, Keyword.t) :: String.t
+  @spec delete(String.t, Keyword.t) :: {:ok, String.t}
   defdelegate delete(path, params \\ []), to: ExTrello.API.BareRequests
 
   @doc """
@@ -533,7 +533,7 @@ defmodule ExTrello do
   ## Reference
   https://trello.com/app-key
   """
-  @spec request_token(String.t) :: ExTrello.Model.RequestToken.t
+  @spec request_token(String.t) :: {:ok, ExTrello.Model.RequestToken.t}
   defdelegate request_token(return_url), to: ExTrello.API.Auth
 
   @doc """

diff --git a/lib/ex_trello/api/boards.ex b/lib/ex_trello/api/boards.ex
@@ -9,10 +9,6 @@ defmodule ExTrello.API.Boards do
   alias  ExTrello.Model.{Board}
 
   # Boards
-  defapicall hey(first, _second) do
-    IO.puts first
-    first
-  end
 
   def boards(), do: boards([])
   defapicall boards(options) when is_list(options) do

diff --git a/mix.exs b/mix.exs
@@ -3,7 +3,7 @@ defmodule ExTrello.Mixfile do
 
   def project do
     [app: :ex_trello,
-     version: "0.5.0",
+     version: "1.0.0",
      elixir: "~> 1.3",
      description: "An Elixir package to interface with the Trello API",
      build_embedded: Mix.env == :prod,