This is a basic skeleton for building a Ruby application/hal+json hypermedia API, which we have used with success at Reverb.com.
It is intended as a jumping off point to build services. The stack of included components:
- Grape for API layer
- Roar for JSON+HAL representers
- ActiveRecord with basic rake tasks for migrations, along with middleware to manage connections within the Rack app.
- Logging middleware for Rack.
- Mina for deployment
- Thin for running the service locally
- Foreman + Upstart for running service on Ubuntu
- Convenieces like a script/console for interacting with your code.
- Rspec for testing, Bogus for mocking and contract tests (ensure mocks are not lying to you)
See the Gemfile for more technology choices.
How to use
- Your code goes into lib/ (organize it how you want)
- This ain't rails.
requireyour classes explicitly. It's a good thing.
- A sample api endpoint has been provided inside the
- We prefer to write one class per API, for example GetFoo or CreateFoo with a single endpoint.
- All API classes should be added to
api/base.rbto get mounted into the app.
- Roar representers go into api/representers. See the Roar for more info. We prefer the decorator style pattern to the mixins.
- The current deployment model uses upstart to restart the service. Even though the service is quick to start, it still has downtime. We can improve this by switching to unicorn and signalling a graceful restart instead.
- This framework includes an ActiveRecord layer. It's pretty easy to swap out for other persistence.
- Logging is pretty rudimentary and can be improved in formatting.
Prior to launching the service, ensure you have migrated the db:
To migrate other environments:
rake db:migrate DATABASE_ENV=production
Start dev env:
Start production env:
For convenience, a rails-like console has been provided:
First, setup the remote server with RVM:
curl -L https://get.rvm.io | bash -s stable --ruby=2.0.0
The first time this server has ever been deployed to, invoke this setup to create the right dirs, first checking deploy.rb for the correct ip address:
mina deploy ENV=production