tomclose / pliny

Write excellent APIs in Ruby

Pliny

Opinionated template Sinatra app for writing excellent APIs in Ruby.

It bundles some of the patterns we like to develop these apps:

• Config: ENV wrapper for explicit defining what config vars are mandatory and optional
• Endpoints: the Sinatra equivalent of a Rails Controller
• Initializers: tiny files to configure libraries/etc (equivalent of Rails)
• Mediators: plain ruby classes to manipulate models
• Models: very thin wrappers around the database

And gems/helpers to tie these together and support operations:

• CORS middleware to allow JS developers to consume your API
• Rollbar for tracking exceptions
• Log helper that logs in data format to stdout
• Mediators to help encapsulate more complex interactions
• Rspec for lean and fast testing
• Puma as the web server, configured for optimal performance on Heroku
• Rack-test to test the API endpoints
• Request IDs
• RequestStore, thread safe option to store data with the current request
• Sequel for ORM
• Sequel-PG because we don't like mysql
• Versioning to allow versioning your API in the HTTP Accept header

Getting started

First make sure the following is installed:

• Postgres
  • The uuid-ossp module for Postgres

Then install the gem:

$ gem install pliny

And initialize a new app:

$ pliny-new myapp
$ cd myapp && bin/setup

Pliny also bundles some generators to help you get started:

$ bundle exec pliny-generate model artist
created model file ./lib/models/artist.rb
created migration ./db/migrate/1408995997_create_artists.rb
created test ./spec/models/artist_spec.rb

$ bundle exec pliny-generate mediator artists/creator
created mediator file ./lib/mediators/artists/creator.rb
created test ./spec/mediators/artists/creator_spec.rb

$ bundle exec pliny-generate endpoint artists
created endpoint file ./lib/endpoints/artists.rb
add the following to lib/routes.rb:
  mount Endpoints::Artists
created test ./spec/endpoints/artists_spec.rb
created test ./spec/acceptance/artists_spec.rb

$ bundle exec pliny-generate migration fix_something
created migration ./db/migrate/1395873228_fix_something.rb

$ bundle exec pliny-generate schema artists
created schema file ./docs/schema/schemata/artist.yaml
rebuilt ./docs/schema.json

To test your application:

$ bundle exec rake

Or to run a single test suite:

$ bundle exec rspec spec/acceptance/artists_spec.rb

Generators

$ bin/pliny-generate

Commands:
  pliny-generate endpoint NAME    # Generates an endpoint
  pliny-generate help [COMMAND]   # Describe available commands or one specific command
  pliny-generate mediator NAME    # Generates a mediator
  pliny-generate migration NAME   # Generates a migration
  pliny-generate model NAME       # Generates a model
  pliny-generate scaffold NAME    # Generates a scaffold of endpoint, model, schema and serializer
  pliny-generate schema NAME      # Generates a schema
  pliny-generate serializer NAME  # Generates a serializer

Rake tasks

Pliny comes with several rake tasks:

rake db:create        # Create the database
rake db:drop          # Drop the database
rake db:migrate       # Run database migrations
rake db:nuke          # Nuke the database (drop all tables)
rake db:reset         # Reset the database
rake db:rollback      # Rollback the database
rake db:schema:dump   # Dump the database schema
rake db:schema:load   # Load the database schema
rake db:schema:merge  # Merges migrations into schema and removes them
rake db:seed          # Seed the database with data
rake db:setup         # Setup the database
rake schema           # Rebuild schema.json

Commands

And provides the following commands:

$ foreman start                             # Starts server
$ foreman run bin/console                   # IRB/Pry console
$ foreman run bin/run 'puts "hello world"'  # Run automated code

(hint: don't forget foreman run in development)

Development

Run tests:

$ bundle install
$ git submodule update --init
$ rake

Meta

Created by Brandur Leach and Pedro Belo.