After I published my blog post on Building a Tested, Documented and Versioned JSON API Using Rails 4, many readers asked me for a sample template app. So here it is. Feel free to send in pull requests.
This is a template Rails 4 app which has the following to start with :
- Rails-API - Rails for API only apps
- Devise for token based authentication
- Cucumber for integration testing + up-to-date API documentation
- Versioning using the "Accept" header
- Does not depend on cookies/session.( In simple words, the API client need not be a browser )
cd rails-4-api
bundle install --without production
RAILS_ENV=test bundle exec rake db:setup #Setup the test DB
bundle exec rake #Build ( RSpec + Cucumber )
#open public/api_doc.html in your browser
I get this question a lot : "Why use Cucumber for API testing ? Why not RSpec controller/request specs ?"
- Cucumber is good at one thing : integration testing using user interaction expressed as steps. API testing = integration testing , where the user = any API client that can interact with the API in the language of HTTP requests. Use Rack::Test for HTTP request/response instead of Capybara for page interaction, now you can write API client interaction as steps and write readable and expressive integration tests.
- I want to use the output of the test suite as documentation for my APIs. Cucumber output is perfect for this, because cucumber forces you to write sequences of steps in a natural language. You would need a hell lot of ruby blocks in RSpec to produce an output that can act as a self explanatory documentation.
- Personal choice. I use RSpec heavily for unit test and I find RSpec is a good fit for that. But writing integration tests in RSpec doesn't look good to me. But to each his own, there's nothing stopping you from using RSpec for the job. Read this excellent blog post to see how you can use RSpec to test APIs