Other videos in this practice series:
- Episode 1: Documenting Your API First
- Episode 2: Mocking APIs with API Blueprint
- Episode 3: Basic Serialization
- Episode 4: Documentation Testing
- Episode 5 & 6: Handling Errors Nicely
Now that we've started building a very basic API, we should make sure that the documentation continues to keep up to date with our progress. Even better, we can use our documentation as a basic contract test, to make sure we aren't lying about what our API offers.
I've written tutorials in the past about how Dredd works, so this video will just go over this stuff in a bit more detail.
You can easily install dredd using npm:
npm install -g dredd
Once installed, you can use its init function to set things up:
With the correct values added, running dredd is a single command. The output can be a llittle verbose, so I like to pipe it to a log file:
dredd > log/dredd.log
For dredd to work, there needs to be data in the database. If you make a request to
/products/1 and there is no record with ID=1 in the database, then it will return a
404 response, instead of a
200 response with all the expected attributes.
To solve this we can use database seeding. A lot of apps use seeding for other things, so it can be really useful to make a custom seed out of the way of anything else:
# lib/tasks/custom_seeds.rake namespace :db do namespace :seed do Dir[File.join(Rails.root, 'db', 'seeds', '*.rb')].each do |filename| task_name = File.basename(filename, '.rb').intern task task_name => :environment do load(filename) if File.exist?(filename) end end end end
Now, we can populate the seeds with really basic record creation. In fact, this is the same stuff we used in episode 3:
# db/seeds/dredd.rb manufacturer = Manufacturer.create(name: "Thatchers", about: "Pretty solid cider makers who are randomly moving their factories in the south west and going to Ireland...", city: "Dublin", country: "Ireland") Product.create(manufacturer: manufacturer, name: 'Katies', description: "Unnecessarily strong fizzy cider that sells for the same price as normal ciders.", apv: 7.6, product_type: 'cider') Product.create(manufacturer: manufacturer, name: 'Thatchers Dry', description: "As the name suggests this is dry, and a little tangy.", apv: 6.5, product_type: 'cider')
To check that works, you can run it with the following command:
In isolation, that is not very helpful. We also don't want to mess with our development database. Using the entire following command, you can use the testing database, create a fresh DB every time, load the schema up, then run dredd.
RAILS_ENV=test rake db:drop db:create db:migrate db:seed:dredd && dredd
This would be a fairly annoying command to have to remember, wrap it up in a simple
# Makefile .PHONY: docs_test docs_test: @echo "Seeding database for documentation testing" @RAILS_ENV=test rake db:drop db:create db:migrate db:seed:dredd @echo "Running dredd... check logs/dredd.log for more information" @RAILS_ENV=test dredd > log/dredd.log && echo "Documentation is all good!"
Makefile in your project root, you can simply run this:
$ make docs_test
We'll be making a few more make commands over the next few videos. They're really useful!
Interested in a Proper Series?
These rough videos will be replaced with a nicely recorded series, and to get updates about that, just let me know your email address.
If you're into APIs, I've written a whole book called Build APIs You Won't Hate, and it's available in ebook or paperback form! If programming books normally bore the crap out of you, this book is for you.