I always dreamt about an API powered website for armoredcode community. I do think that every website should publish some sort of API to use services.

That’s why APIs for armoredcode are online.

I started last week hanging out on this project. Sinatra is the standard de facto choice for building an API with ruby but, which framework to be used on top of this? Is there out there something I can use to quickstart my project?

The answer is yes, it’s called grape. Grape is a micro-framework built on top of Rack that provides a DSL to write APIs.

So let’s start the my first coding run. The goal is to implement an API to provide gengiscan as SaaS for people don’t want to install and run my gem on their machine.

Layout

Source code layout is the standard Sinatra application. Some service files on the root dir, the magic app.rb file, public, tmp and spec folders.

Gemfile is very basic. We will use gengiscan starting from version 0.40 that introduces better error checking and we will use grape. We will make TDD so we are going to use rspec and rack-test to write tests for our API.

``` ruby Gemfile source ‘https://rubygems.org’

gem ‘bundler’ gem ‘grape’ gem ‘json’ gem ‘gengiscan’, “>=0.40” gem ‘rake’, :groups=>[:development, :test] gem ‘rack-test’, :group=>:test gem ‘rspec’, :group=>:test

Rakefile is in place just to provide rspec tasks. No great deals in this.

``` ruby Rakefile
#!/usr/bin/env rake
require "rspec/core/rake_task"

RSpec::Core::RakeTask.new

task :default => :spec
task :test => :spec

TDD, let’s do testing

Grape page at github is great in giving help on using rspec.

``` ruby spec_helper.rb require “rack/test” require ‘./app’

As a behavior I want a [gengiscan api url](http://api.armoredcode.com/api/v1/gengiscan)
 that it will be called using POST HTTP method and the caller must give an host
parameter and an optional port in the HTTP POST request.

Of course, there is also an [hello world](http://api.armoredcode.com/api/v1/hello).

``` ruby api_spec.rb
require 'spec_helper'

describe ArmoredAPI do
  include Rack::Test::Methods

  def app
    ArmoredAPI
  end

  describe ArmoredAPI do
    describe 'GET /api/v1/hello' do
      it 'says hello to the world' do
        get "/api/v1/hello"
        last_response.status.should == 200
        JSON.parse(last_response.body)["hello"].should == "world"
      end
    end

    describe 'GET /api/v1/gengiscan' do
      it 'returns a 404 error if no host is provided' do
        get "/api/v1/gengiscan"
        last_response.status.should == 404
      end

      it 'run gengiscan over localhost' do
        post "/api/v1/gengiscan", "host"=>"localhost"
        last_response.status.should == 201
        hash = JSON.parse(last_response.body)
        hash["status"].should == "OK"
      end

      it 'run gengiscan over localhost on a port different than 80' do
        post "/api/v1/gengiscan", "host"=>"localhost", "port"=>"4000"

        last_response.status.should == 201
        hash = JSON.parse(last_response.body)
        hash["status"].should == "OK"
      end
    end
  end
end

I can improve my tests more mocking up a webserver, with plenty of response using webmock I used for gengiscan but it will be a further enhancement.

The API source code

You can imagine a complex ruby application that makes all of these tests going green. You’re wrong. Just 26 lines of code including empty lines thanks to grape.

``` ruby app.rb require ‘grape’ require ‘gengiscan’ require ‘json’

class ArmoredAPI < Grape::API prefix ‘api’ version ‘v1’

get ‘hello’ do {:hello => ‘world’}.to_json end

desc ‘Identify you host’ namespace :gengiscan do

post do
  host = "localhost"
  port = "80"

  host = request.params["host"] unless request.params["host"].nil?
  port = request.params["port"] unless request.params["port"].nil?
  Gengiscan::Engine.new.detect("http://#{host}:#{port}").to_json
end   end end ``` 

With the prefix and version keywords I fixed that all the following url calls start at ‘/api/v1’.

Saying hello to the world is very easy as you may expect from a rack powered application.

``` ruby the /hello api get ‘hello’ do {:hello => ‘world’}.to_json end

``` ruby
$ curl http://api.armoredcode.com/api/v1/hello
{"hello":"world"}% 

Handling gengiscan is easy as well. You’ve just to take care about parameter in the request. I used a namespace since I want a clear source code if I’ll add (and I’ll do) a get handler explaining how to use the gengiscan API.

``` ruby Fingerprinting armoredcode.com $ curl -d “host=armoredcode.com” http://api.armoredcode.com/api/v1/gengiscan {“status”:”OK”,”code”:”200”,”server”:”nginx/1.0.14”,”powered”:null,”generator”:””}%

``` ruby Fingerprinting armoredcode.com on a closed port
$ curl -d "host=armoredcode.com;port=3000" http://api.armoredcode.com/api/v1/gengiscan
{"status":"KO","code":null,"server":null,"powered":null,"generator":null}%       

That’s all. You can POST your requests to gengiscan api specifying the host to fingerpring in the host parameter and you’ve got an optional port parameter if the server accept connection on non standard HTTP 80 port.

As far as today, making requests on HTTP is hardcoded so you can’t fingerprint an HTTPS powered server even mimic a connection on port 443.

$ curl -d "host=gmail.com;port=443" http://api.armoredcode.com/api/v1/gengiscan
{"status":"KO","code":null,"server":null,"powered":null,"generator":null}% 

Enjoy it.