Cabal::API
Cabal is a simple system for SSH key distribution and consumption. This is the HTTP API that acts as the basis for both of those operations.
Installation
Add this line to your application's Gemfile:
gem 'cabal-api', require: 'cabal/api'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cabal-api
Usage
This API is implemented via Grape, which means that you can mount it the same way that you can any Rack application. You'll need a Redis endpoint for the API to use (it defaults to redis://localhost:6379
), and this is configured via the REDIS_URL
environment variable.
Here's an example config.ru
that mounts the API to the "/api" namespace:
require 'cabal/api'
map "/api" do
run Cabal::API::Base
end
You can then start that configuration like so:
REDIS_URL="redis://your-redis-server:port/db" rackup config.ru
APIv1
The v1 API is entirely public (no authenticated routes). The routes for this version are as follows (provided that the API is mounted on "/api"):
- GET /api/v1/key/clustername
This returns the public key for the given cluster name. If the cluster is not already known, it is created and a key is generated. Supported formats are:
- text - Returns the key raw
- json - Returns an object with
name
andpublic_ssh_key
attributes- xml - Returns a "hash" document with
name
andpublic_ssh_key
elements
APIv2
The v2 API is made up of both public and private routes. Authentication is performed by setting the Authorization
request header to API_KEY:API_SECRET
prior to performing the request.
- (public) GET /api/v2/key/clustername
This route is exactly equivalent to the
v1
key route.
- (private) GET /api/v2/private-key/clustername
Returns the private key for the requested cluster. If the cluster is not already known, the request results in a 404. If authentication credentials are missing or invalid, the request results in a 404. Otherwise, the result depends on format:
- text - Returns the raw key
- json - Returns an object with
name
andprivate_ssh_key
attributes- xml - Returns a "hash" document with
name
andprivate_ssh_key
elements
APIv2
The v3 API is made up of both public and private routes. Authentication is performed by setting the Authorization
request header to API_KEY:API_SECRET
prior to performing the request.
- (public) GET /api/v3/key/clustername
This route is exactly equivalent to the
v1
key route.
- (private) GET /api/v3/private-key/clustername
This route is exactly equivalent to the
v2
private-key route.
- (private) GET /api/v3/clusters
Returns the names of the clusters known to the API in the following format:
- text - Returns a list of cluster names, one per line
- json - Returns an array of objects with
name
attributes- xml - Returns an "array" document containing "hash" elements with a
name
element
Development
Branches and releases for this project are managed by git-flow.
After checking out the repo, run bin/setup
to install dependencies. Then, run bin/console
for an interactive prompt that will allow you to experiment.
Contributing
Note: Please base all feature branches on the develop
branch.
- Fork it ( https://github.com/engineyard/cabal-api/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request against the
develop
branch