Add specs and docs

Author: LindseyB

.gitignore

@@ -1,4 +1,2 @@
-.bundle/*
-log/*
 *.swp
 *.swo

README.md

@@ -1,14 +1,114 @@
+# Tarot Api
+
+## Requests
+
+`GET /`
+
+Returns an array of every card
+
+`GET /cards`
+
+Returns an array of every card
+
+`GET /cards/[suit]/[rank]`
+
+| argument | values                                                                  | required |
+|----------|-------------------------------------------------------------------------|----------|
+| suit     | one of: swords, wands, cups, coins, or major                            | yes      |
+| rank     | one of: king, queen, 1-10 for swords/wands/cups/coins or 0-21 for major | yes      |
+
+Returns a single card in the form of
+
+| field              | type             | description                                                                                 |
+|--------------------|------------------|---------------------------------------------------------------------------------------------|
+| fortune_telling    | array of strings | what this card might mean in a fortune                                                      |
+| keywords           | array of strings | what words are associated with this card                                                    |
+| meanings           | hash             |                                                                                             |
+| meanings["light"]  | array of strings | meanings for this card in the upright position                                              |
+| meanings["shadow"] | array of strings | meanings for this card in the reverse position                                              |
+| name               | string           | the name of the card written out in words                                                   |
+| rank               | string or int    | rank of the card in the suit up to 21 for major arcana, king through 10 for all other suits |
+| suit               | string           | major, coins, cups, swords, or wands                                                        |
+
+### Example
+
+`GET /cards/swords/10`
+
+<details>
+  <summary>
+    returns the following JSON
+  </summary>
+
+  ```JSON
+  {
+   "fortune_telling":[
+      "Disaster",
+      "Put off plans and do not take action until omens are better"
+   ],
+   "keywords":[
+      "exhaustion",
+      "ruin",
+      "disaster",
+      "stamina",
+      "obsession"
+   ],
+   "meanings":{
+      "light":[
+         "Seeing the signs that you've reached your limits",
+         "Paying attention to what your body is trying to tell you",
+         "Giving in to the need for rest and renewal",
+         "Acknowledging that you've hit bottom",
+         "Committing to a turnaround",
+         "Knowing the worst is over"
+      ],
+      "shadow":[
+         "Accepting defeat prematurely",
+         "Driving yourself to total exhaustion, especially mentally",
+         "Experiencing a mental breakdown",
+         "Obsessing on a problem to the breaking point",
+         "Giving up",
+         "Refusing to move from thought to action",
+         "Deeply unhealthy thoughts"
+      ]
+   },
+   "name":"ten of swords",
+   "rank":10,
+   "suit":"swords"
+  }
+  ```
+</details>
+
+`GET /draw/[n]`
+
+Returns n randomly selected cards
+
+| argument | values       | required |
+|----------|--------------|----------|
+| n        | positive int | yes      |
+
+`GET /find/:name`
+
+Returns the card by the specified name. Note that the numbers will be spelled out and pentacles will be replaced by coins.
+
+| argument | values                                     | required |
+|----------|--------------------------------------------|----------|
+| name     | string name of the card (eg: The Magician) | yes      |
+
 
 ## Testing
 
-  rake spec
+  ```
+  rake test
+  ```
 
 ## Getting Started
 
+  ```
   bundle install
-  rake db:migrate
-  shotgun application.rb
+  rackup
+  ```
 
 ## Thanks
 
-Sinatra API template https://github.com/noplay/sinatra-api-template
+* Sinatra API template https://github.com/noplay/sinatra-api-template
+* Tarot Corupus from https://github.com/dariusk/corpora

Rakefile

@@ -2,15 +2,13 @@ require 'rubygems'
 require 'bundler/setup'
 require 'rspec/core/rake_task'
 
-task :default => :test
-task :test => :spec
+task default: %w[server]
 
-if !defined?(RSpec)
-  puts "spec targets require RSpec"
-else
-  desc "Run all examples"
-  RSpec::Core::RakeTask.new(:spec) do |t|
-    #t.pattern = 'spec/**/*_spec.rb' # not needed this is default
-    t.rspec_opts = ['-cfs']
-  end
+task :server do
+  sh "rackup --host 0.0.0.0"
 end
+
+task :test do
+  RSpec::Core::RakeTask.new(:spec)
+  Rake::Task["spec"].execute
+end

application.rb

@@ -36,9 +36,9 @@ def halt_with_403_forbidden_error(message = nil)
   # return card by suit and rank
   get '/cards/:suit/:rank' do
     suit = params[:suit].downcase.gsub("pentacles", "coins")
-    rank = params[:rank].downcase
+    rank = params[:rank].downcase # ranks can be strings or ints
 
-    card = cards.detect { |card| card["rank"] == rank.to_s && card["suit"] == suit }
+    card = cards.detect { |card| card["rank"].to_s == rank && card["suit"] == suit }
     halt_with_404_not_found unless card
     json card
   end

spec/application_spec.rb

@@ -1,14 +1,115 @@
-require "#{File.dirname(__FILE__)}/spec_helper"
-
-describe 'main application' do
-  include Rack::Test::Methods
+require "spec_helper"
 
+describe 'Application' do
   def app
-    Sinatra::Application.new
+    Application
+  end
+
+  describe "/" do
+    it "should return all cards" do
+      get "/"
+      expect(last_response).to be_ok
+
+      expect(last_response.body).to include("The Magician")
+      expect(JSON.parse(last_response.body).length).to eq 78
+    end
+  end
+
+  describe "/cards" do
+    it "should return all cards" do
+      get "/cards"
+      expect(last_response).to be_ok
+
+      expect(last_response.body).to include("The Magician")
+      expect(JSON.parse(last_response.body).length).to eq 78
+    end
   end
 
-  specify 'should show the default index page' do
-    get '/'
-    last_response.should be_ok
+  describe "/cards/:suit/:rank" do
+    it "returns the specified card" do
+      get "/cards/major/1"
+      expect(last_response).to be_ok
+
+      card = JSON.parse(last_response.body)
+      expect(card["name"]).to eq "The Magician"
+      expect(card["suit"]).to eq "major"
+      expect(card["rank"]).to eq 1
+    end
+
+    it "is case insensitive" do
+      get "/cards/sWoRdS/QuEeN"
+      expect(last_response).to be_ok
+
+      card = JSON.parse(last_response.body)
+      expect(card["name"]).to eq "queen of swords"
+      expect(card["suit"]).to eq "swords"
+      expect(card["rank"]).to eq "queen"
+    end
+
+    it "replaces pentacles with coins" do
+      get "/cards/pentacles/10"
+      expect(last_response).to be_ok
+
+      card = JSON.parse(last_response.body)
+      expect(card["name"]).to eq "ten of coins"
+      expect(card["suit"]).to eq "coins"
+      expect(card["rank"]).to eq 10
+    end
+
+    it "returns a 404 if card not found" do
+      get "/cards/cats/dash"
+      expect(last_response).to be_not_found
+    end
+  end
+
+  describe "/draw/:n" do
+    it "returns the number of requested cards" do
+      get "/draw/3"
+      expect(last_response).to be_ok
+
+      expect(JSON.parse(last_response.body).length).to eq 3
+    end
+
+    it "returns an error if negative cards requested" do
+      get "/draw/-1"
+      expect(last_response).to be_forbidden
+    end
+  end
+
+  describe "/find/:name" do
+    it "returns the specified card" do
+      get "/find/The%20Magician"
+      expect(last_response).to be_ok
+
+      card = JSON.parse(last_response.body)
+      expect(card["name"]).to eq "The Magician"
+      expect(card["suit"]).to eq "major"
+      expect(card["rank"]).to eq 1
+    end
+
+    it "is case insensitive" do
+      get "/find/thE%20magician"
+      expect(last_response).to be_ok
+
+      card = JSON.parse(last_response.body)
+      expect(card["name"]).to eq "The Magician"
+      expect(card["suit"]).to eq "major"
+      expect(card["rank"]).to eq 1
+    end
+
+    it "replaces pentacles with coins" do
+      get "/find/ten%20of%20pentacles"
+      expect(last_response).to be_ok
+
+      card = JSON.parse(last_response.body)
+      expect(card["name"]).to eq "ten of coins"
+      expect(card["suit"]).to eq "coins"
+      expect(card["rank"]).to eq 10
+    end
+
+    it "returns 404 if card not found" do
+      get "/find/dash"
+      expect(last_response).to be_not_found
+    end
   end
 end

spec/spec_helper.rb

@@ -1,14 +1,11 @@
-require 'rubygems'
-require 'bundler'
-Bundler.setup(:default, :test)
-require 'sinatra'
-require 'rspec'
-require 'rack/test'
+# spec/spec_helper.rb
+require "rack/test"
+require "rspec"
 
-# set test environment
-Sinatra::Base.set :environment, :test
-Sinatra::Base.set :run, false
-Sinatra::Base.set :raise_errors, true
-Sinatra::Base.set :logging, false
+ENV["RACK_ENV"] = "test"
 
-require File.join(File.dirname(__FILE__), '../application')
+require File.expand_path "../../application.rb", __FILE__
+
+RSpec.configure do |config|
+  config.include Rack::Test::Methods
+end