API-First Training: Blackjack API

This is the JSON API compliant server application being developed as part of the API-First seminar.

The goal of our application is to implement the complete rules of Blackjack, the most widely played casino game in the world.

Why Blackjack?

• It's a bit complicated! I wanted to choose a domain that had some difficult modeling questions without an obvious correct answer.
• It's fun! Whether or not you like to gamble, it's fun to work on a game.
• It's familiar! Most people have some familiarity with the game which should make the domain accessible enough.

Can I play a game?

Not yet! It will take some time to finish the implementation of the full game. We'll work on it a bit more each time that we conduct this seminar. For now, we're about 1/4 of the way through building the complete application.

Installation

First, let's get the system dependencies out of the way:

1. Ruby: The application was developed and tested using Ruby 2.2.3. It's preferable for you to run the same version (to eliminate any unexpected issues), but if you need to run a less recent version you can try. You'll need to edit the Gemfile to reflect that change in your fork. I use rbenv to manage my Rubies, but you can use whatever way you prefer.
2. PostgreSQL: We'll be using the PostgreSQL database. If you don't have it installed already, try Postgres.app. If you're not using a Mac and don't know how to install PostgreSQL, it would probably be easiest to use Heroku Postgres.

Next, fork this repository and clone it to your machine.

Then, cd into the project directory and run bin/setup. That will install bundler if necessary, run bundle install, and then setup the database.

Next, run the test suite with bin/rspec.

If everything is working fine you should see the application boot without error and all the tests pass.

To build the documentation for the application, run bundle exec rake docs:generate. That will add the static documentation files to the docs directory which is rebuilt by Codeship every time the app is deployed.

Next, boot your server with foreman start.

Visit http://localhost:5000 and you'll be redirected to the documentation. That's it!

Libraries

• JSON API: The application conforms to the JSON API specification.
• jsonapi-resources: We'll be using this gem to generate the controller actions and serializers for our resources.
• doorkeeper: We'll only use OAuth2 for authentication in the most basic way, but it still can feel tricky if you're new to it.
• pundit: Pundit is the authorization library and approach that we'll use. It's a bit different from cancancan and similar approaches and integrated into jsonapi-resources in a novel way in this application.
• rspec: We'll use RSpec heavily for all of our testing. I've kept things simple as much as possible, but if you're not used to RSpec it would be worth it to familiarize yourself.
• rspec_api_documentation: This library is used to output API documentation as a byproduct of acceptance tests. We'll use apitome to format the output.

Deployment

• Codeship: We'll use a continuous integration server on Codeship. It will run the test suite with every commit that is pushed to GitHub and also rebuild the API documentation for us. Let's show this now!
• Heroku: We'll use Heroku Pipelines to manage staging and production environments. The staging server will automatically rebuild every time there is a commit to the documented branch. We'll also use the Review Apps feature to build applications for PRs.

Documentation

Documentation for the API is automatically generated by rspec_api_documentation. Codeship rebuilds the docs with every commit to the master branch and deploys them to Heroku.

https://blackjack-api-staging.herokuapp.com/v1/docs

Contributing

You are sure to see typos, missing features, missing documentation, bugs, and code that needs to be refactored. Please send pull requests so that we can improve the code and learn as a group!

💜💚 @barelyknown