Skip to content
Kemal API Version Extension
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
spec
src
.gitignore
.travis.yml
LICENSE
README.md
shard.yml

README.md

Kave (Kemal API Version Extension)

This shards makes it easier to version your Kemal API

Installation

Add this to your application's shard.yml:

dependencies:
  kave:
    github: jwoertink/kave

Usage

require "kemal"
require "kave"

Kave.configure do |c|
  # These are default config options
  # c.format = :json                # see Formats below
  # c.auth_strategy = nil           # see Auth Strategy below
  # c.token_model = Kave::AuthToken # see Auth Strategy below
  # c.version_strategy = :header    # see Version Strategy below
end

public do
  get "/" do |env|
    "This is a public route"
  end
end

api("v1") do
  get "/" do |env|
    "This is a private route only accessed through the version 1 API"
  end

  before_post "/check" do |env|
    "This is called before POST /v1/check"
  end
  post "/check" do |env|
    "something here"
  end
end

api("v2") do
  get "/" do |env|
    "This is a private route only accessed through the version 2 API"
  end
end

Configuration Options

Formats

The formats are how your data will be returned. By default, Kave will assume you're building a JSON API. Kave will automatically set your response Content-Type to match the type of API you're building.

For now, you must handle the data conversion yourself, but eventually Kave will take care of that for you.

# assumes format is :json
api("v1") do
  get "/users/:id" do |env|
    {"id" => env.params.url["id"], "name" => "jeremy"}.to_json
  end
end

You would make a call to this route by http://localhost:3000/v1/users/1

Additional options later will be :xml, :msgpack, :plain

Auth Strategy

If your API isn't public, then you'll probably want to add some sort of API key. By default, Kave sets the auth_strategy to nil, but you can use a Bearer token authorization. To use this, set the auth_strategy to :bearer, and create a class that inherits from Kave::AuthToken. Set the token_model to your custom class, and make sure that class implements the class method locate.

class MyTokenModel < Kave::AuthToken
  def self.locate(token : String)
    token == "abc123"
  end
end

Kave.configure do |c|
  c.auth_strategy = :bearer
  c.token_model = MyTokenModel
end

api("v1") do
  get "/users/:id" do |env|
    {"id" => env.params.url["id"], "name" => "jeremy"}.to_json
  end
end

To access this route:

$ curl -H "Authorization: Bearer abc123" "http://localhost:3000/v1/users/1"

Version Strategy

By default, Kave will generate paths for your API by prepending the version to your route like /v1/whatever. This option gives you the ability to specify your routes like /whatever and control the version using a header. Later there may be an option like :subdomain to do v1.whatever.com/whatever.

Kave.configure do |c|
  c.version_strategy = :header
end

api("v1") do
  get "/users" do |env|
    [{"id" => 1, "name" => "Jeremy"}].to_json
  end
end

To access this route:

$ curl -H "Accept: application/vnd.api.v1+json" "http://localhost:3000/users"

NOTE In a previous version of Kave you were able to change this halfway through. I realized after lots of trail and error that this was going to cause a huge mess. You can't conditionally add middleware. It's either there, or it's not. I may add that back in later if I can come up with some clever way, but until people start asking for that, it's out for now.

Development

This is going to be a work in progress for a while. If you have a better idea for how something should be implemented, please open an issue, or submit a PR.

Contributing

  1. Fork it ( https://github.com/jwoertink/kave/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Make sure all specs pass
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request

Contributors

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.