Ki Framework

Build Status Code Climate Test Coverage

Tiny REST JSON ORM framework with MongoDB.

Ki's goal is to help you protoype your ideas blazing fast. It has a db backend and provides a fullblown REST api on top.

Table of Contents


To create an api endpoint '/todo.json' with GET/POST/PATCH and restricting DELETE, with title and description as required attributes, with db backend, with a unique title, and before/after filters you would need to write:

class Todo < Ki::Model
  requires :title, :description
  unique :title
  forbid :delete

  def before_all
    puts 'hello'

  def before_create
    params['created_at'] =

  def after_find
    if result['keywords'].include? 'food'
      puts 'yummy'


gem install ki

Getting started

Learn by example. We will create the traditional 'hello world' app for web development: the dreaded TODO app.

View the code for the final webapp.

Create a new app

ki new todo

This will create the folder todo containing a bare bones ki application. Your app will look like this.

App directory structure:

  • public/
    • javascripts/
    • stylesheets/
  • views/
  • app.rb
  • config.yml

The entry point for the app is app.rb. You will add most of your code there. Views are in the views folder and you can find some database info in config.yml.

cd todo
ki server

ki server is the command which starts the webserver. By default it starts on port 1337.

For an interactive environment, you can run the console command. It starts a irb session with your application context already loaded.

ki console


ki supports realtime communication though WebSockets

To learn how to use the realtime api, read this.

Adding a view

A view is a html page. By default, a view called 'index.haml' is created for you in the 'views/' folder. All haml files from the '/views/' folder are compiled to html at runtime.

For example, to serve a html file when a user accesses '/dashboard' create the 'views/dashboard.haml' dashboard.

Adding assets

All files from the 'public/' folder are served to the client from the root url.

You can add any type of file. Coffee and sass files are compiled at runtime, similar to haml.

View layout

If the file views/layout.haml exists, it will be used as a layout for all the other haml files. The content of the route will be placed in the layout yield


    %title Ki Framework
    = yield


%p Hello World!


Views, assets, haml, less, sass are all handled through Rack middleware.

You can learn more about ki middleware here.


To reduce complexity in your views, you can use helpers. Here we create a say_hello method which we can use in views/index.haml.


module Ki::Helpers
  def say_hello


%p= say_hello

Adding a resource

Think of resources as the M in MVC. Except they also have routes attached. All resources must inherit from Ki::Model. For example, to create a todo model add the fallowing snippet to app.rb

class Todo < Ki::Model

This will create the Todo resource and its corresponding routes. Each route is mapped to a model method.

Method name Verb HTTP request Required params
find GET /todo.json
create POST /todo.json
update PATCH /todo.json id
delete DELETE /todo.json id

Below is a curl example for creating a todo item. Notice the data sent in the body request is a JSON string. It can take the shape of any valid JSON object. All json objects will be stored in the database under the resource name. In our case todo.


curl -X POST -d '{"title": "make a todo tutorial"}' http://localhost:9292/todo.json

Get all

curl -X GET http://localhost:9292/todo.json

Get by id

curl -X GET http://localhost:9292/todo.json?id=ITEM_ID

Advanced queries

Mongo syntax is supported. See here for more details.

Some examples:

Search in array

curl -k -X GET -d '{"category": {"$in": ["music"]}}' ""

Greater than number

curl -k -X GET -d '{"i": {"$gt": 0}}' ""

OR Query

curl -k -X GET -d '{"$or": [{"category": "music"}, {"category": "band"}]}' ""

To limit the number of results use a param called __limit and the value desired. For example, the request below will limit itself to 10 results.

curl -k -X GET -d '{"__limit": 10}' ""

To sort the results, use a param called __sort and the key value desired. Example

curl -k -X GET -d '{ "name": "desc" }' ""


curl -X PATCH -d '{"id": "ITEM_ID", "title": "finish the todo tutorial"}' http://localhost:9292/todo.json


curl -X DELETE -d http://localhost:9292/todo.json?id=ITEM_ID


To access headers, simply call @req.headers. In this example, the headers are returned by the API.

class Headers < Ki::Model
  def after_find
    @result = @req.headers

Required attributes

You can add mandatory attributes on resources with the requires method. It takes one parameter or an array of parameters as an argument.

class Todo < Ki::Model
  requires :title

This will make sure a Todo item can not be saved or updated in the database without a title attribute.

Unique attributes

You can add unique attributes on resources with the unique method. It takes one parameter or an array of parameters as an argument.

class Todo < Ki::Model
  unique :title

This will make sure a Todo item can not be saved or updated in the database if it is not unique.

Restricting resource requests

Let's say you want to forbid access to deleting items. You can do that with the forbid method.

class Todo < Ki::Model
  forbid :delete

Before/after callbacks

The framework has these callbacks. Here is an example on how to use them:

class Todo < Ki::Model
  def before_create
    # do your stuff

Accessing the json object within a callback

Before the request is sent to the client, you can look at the result through the result method. Modifying it will change what the client receives.

class Todo < Ki::Model
  def after_find
    puts result


A list of exceptions can be found here

class Todo < Ki::Model
  def before_all


  def ensure_authorization
    if params[:key] = 'secret-key'


redirect_to param

By setting the param redirect_to, you can set an endpoint on where to redirect once the request is completed.



It has a file. Ki is based on rack. You can deploy anywhere (ex: nginx, thin, apache, webrick).

In the webserver config, just remember to point the virtual host to the public directory.

Heroku deployment

ki new heroku-ki
cd heroku-ki
git init
git add .
git commit -m 'initial commit'
heroku create
heroku config:set MONGODB_URI="mongodb://user:pass@mongo_url:mongo_port/db_name"
git push heroku master
heroku open

CORS enabled



Ki offers instant documentation. Add the middleware 'DocGenerator' and access /instadoc.

Administration Interface

Ki offers an instant administration interface. Add the middleware 'AdminIntefaceGenerator' and access /instadmin.


Ki offers a simple task framework. More info here.