Home

Awesome

napa-v2-01-cropped-resized

Circle CI Dependency Status Code Climate Test Coverage

Napa is a simple framework for building Rack based APIs using Grape, Roar and ActiveRecord. It's designed to make it easy to quickly create and deploy new API services by providing generators, middlewares and a console similar to what you would expect from a Rails app.

Installation

Napa is available as a gem, to install it run:

gem install napa

Or, if you're using Bundler, add it to your Gemfile:

gem 'napa'

And run:

$ bundle install

Getting Started

See the Quickstart Guide for an intro to creating a simple service with Napa.

Usage

Run napa terminal prompt to see available features:

Commands:
  napa console [ENVIRONMENT]  # Start the Napa console
  napa deploy [TARGET]        # Deploys A Service to a given target (i.e. production, staging, etc.)
  napa generate [COMMAND]     # Generate new code
  napa help [COMMAND]         # Describe available commands or one specific command
  napa new <NAME> [PATH]      # Create a new Napa application
  napa server                 # Start the Napa server
  napa version                # Shows the Napa version number

Console

Similar to the Rails console, load an IRB session with your applications environment by running:

napa console

Deploy

Napa provides a CLI for deploying to a given environment by setting a git tag. This is useful for chef-based deploys where deploys are trigged when a git SHA changes.

napa deploy production
Are you sure you want to deploy this service? Y
#=> <git SHA> tagged as production by danielmackey at October 09, 2014 14:41

If you want to skip the 'Are you sure?' prompt, pass the --confirm flag to set the tag automatically

napa deploy production --confirm
#=> <git SHA> tagged as production by danielmackey at October 09, 2014 14:41

Rake Tasks

rake -T will give you a list of all available rake tasks:

rake db:create          # Create the database
rake db:drop            # Delete the database
rake db:migrate         # Migrate the database through scripts in db/migrate
rake db:reset           # Create the test database
rake db:schema:dump     # Create a db/schema.rb file that can be portably used against any DB supported by AR
rake db:schema:load     # Load a schema.rb file into the database
rake db:seed            # Load the seed data from db/seeds.rb
rake git:set_tag[tag]   # Set tag, which triggers deploy
rake git:verify         # Verify git repository is in a good state for deployment
rake routes             # display all routes for Grape

Middlewares

Napa includes a number of Rack middlewares that can be enabled to add functionality to your project.

Authentication

The Authentication middleware will add a simple header based authentication layer to all requests. This is just looking for a header of 'Passwords' = 'Your Password'. The passwords are defined in the .env file. You can allow multiple passwords by supplying a comma separated list. For example:

ALLOWED_HEADER_PASSWORDS='password1,password2'

If your application doesn't require authentication, you can simply remove the middleware.

Health Check

The Health Check middleware will add an endpoint at /health that will return some data about your app. This was created to allow monitoring tools a standardized way to monitor multiple services. This endpoint will return a response similar to this:

{
    "name": "service-name",
    "hostname": "host-name",
    "revision": "current-git-sha-of-app",
    "pid": 1234,
    "parent_pid": 1233,
    "napa_revision": "running-version-of-napa"
}

Logger

The Logger module is used to create a common log format across applications. The Logger is enable via a rack middleware by adding the line below to your config.ru file:

use Napa::Middleware::Logger

You can also enable the logger for ActiveRecord by adding the following line to an initializer:

ActiveRecord::Base.logger = Napa::Logger.logger

Napa::Logger.logger returns a Singleton instance of the Logging object, so it can be passed to other libraries or called directly. For example:

Napa::Logger.logger.debug 'Some Debug Message'

Scrubbing Logs of Sensitive Data

Some requests may contain sensitive information, such as passwords or credit card numbers. In order to protect this information, they should be filtered out from logs.

To do so, add the following line to an initializer:

Napa::ParamSanitizer.filter_params = [:password, :password_confirmation, :cvv, :card_number]

Note that the keys in the array above are just examples. They should be replaced with the parameters that have sensitive data in their value.

Example unfiltered request ( ... denotes other information):

{ ... "message":{"request":{"method":"POST","path":"/example","query":"name=Test%20User%200039\u0026password=password", ... "params":{"name":"Test User 0039","password":"password"} ...}}}

Example filtered request ( ... denotes other information):

{ ... "message":{"request":{"method":"POST","path":"/example","query":"name=Test%20User%200039\u0026password=[FILTERED]", ... "params":{"name":"Test User 0039","password":"[FILTERED]"} ...}}}

StatsD

There are two middlewares available to enable StatsD reporting, RequestStats and DatabaseStats. They can be enabled independently in your config.ru file:

use Napa::Middleware::RequestStats
use Napa::Middleware::DatabaseStats

RequestStats will emit information about your application's request count and response time.

DatabaseStats will emit information from ActiveRecord about query times.

Configuration

To configure StatsD in your application you will need to supply the STATSD_HOST and STATSD_PORT in your environment. Optionally, if your StatsD host requires an api token (i.e. hostedgraphite), you can configure that with the STATSD_API_KEY environment variable.

Logging

If you want to see the StatsD reporting in action you can hook up the logger to the Napa logger to see the requests in your logs.

Statsd.logger = Napa::Logger.logger

Caching

Napa adds a simple wrapper around ActiveSupport::Cache that allows you to easily access it similar to how it works in Rails. Napa.cache will give you access to all of the methods available in ActiveSupport::Cache::Store http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html. So, for example:

Napa.cache.read
Napa.cache.write
Napa.cache.fetch
...

By default it will use :memory_store, but you can override it to use any other caching strategy, like Memcache by setting the store:

Napa.cache = :dalli_store

Sorting

Napa has an optional module you can include in any Api called Napa::SortableApi. To include this, add include SortableApi in the helpers block of the Api.

SortableApi takes in a parameter for sort in the format of field1,field2,-field3, where field1 and field2 are used to sort ascending, and field3 is sorted descending. For example, -field4,field1 would be equivalent to `ORDER BY field4 DESC, field1'.

Call sorted_from_params(ar_relation, params[:sort]) passing in an ActiveRecord::Relation for ar_relation, and a comma-delimited string of field names for params[:sort].

Bugs & Feature Requests

Please add an issue in Github if you discover a bug or have a feature request.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request