Spore


Reference

Global Functions

new_from_spec( desc1, [desc2, ...][, { options }] )

Instanciate a ReST client from one or more descriptions defined by a filename or an URL.

The optional table options allows to overwrite some parameters of the description:

local client = require 'Spore'.new_from_spec 'github.json'

new_from_string( desc1, [desc2, ...][, { options }] )

Same as new_from_spec, but works with inline description.

local client = require 'Spore'.new_from_string [[
{
    "base_url" : "http://smolder.parrot.org",
    "name" : "smolder",
    "methods" : {
        "upload" : {
            "path" : "/app/projects/process_add_report/:project_id",
            "method" : "POST",
            "form-data" : {
                "architecture"  : ":architecture",
                "platform"      : ":platform",
                "tags"          : ":tags",
                "comments"      : ":comments",
                "username"      : ":username",
                "password"      : ":password",
                "project_id"    : ":project_id",
                "report_file"   : "@:report_file"
            },
            "required_params" : [
                "project_id",
                "report_file",
                "username",
                "password"
            ],
            "optional_params" : [
                "architecture",
                "platform",
                "tags",
                "comments"
            ],
            "expected_status" : [ 302 ]
        }
    }
}
]]

local r = client:upload{
    tags         = 'linux, i686-linux-gnu-thread-multi, lua, 5.1',
    comments     = 'experiment with lua-Spore',
    username     = 'parrot-autobot',
    password     = 'qa_rocks',
    project_id   = 7,
    report_file  = 'test_lua51.tar.gz',
}
print(r.body)

new_from_lua( desc [, { options }] )

Instanciate a ReST client from a Lua table.

The optional table options allows to overwrite some parameters of the description (see new_from_spec).

local client = require 'Spore'.new_from_lua{
    base_url = 'http://services.org/restapi/',
    methods = {
        get_info = {
            path = '/show',
            method = 'GET',
        },
        get_user_info = {
            path = '/show',
            method = 'GET',
            required_params = {
                'user',
            },
        },
    },
}

local r = client:get_user_info{ user = 'John' }

Instance Methods

These methods are inherited from Spore.Core (so, do not use these name in API description).

enable( middleware [, args] )

Enable a middleware with the optional table args.

enable_if( cond, middleware [, args] )

Enable a conditional middleware.

client:enable_if(function (req)
                     return req.env.spore.caller ~= 'get_attachment'
                 end,
                 'Format.JSON')

reset_middlewares()

Removes all middlewares.

http_request( env )

Never directly called.

Global Variables

These variables allow to do some configuration.

debug

The default value is nil.

require 'Spore'.debug = io.stdout

errors

The default value is io.stderr.

methname_modifier

The default value is nil.

This function allows to alter the name of the method during the instanciation.

require 'Spore'.methname_modifier = function (name)
    local lowerCamelCase = name:gsub('_(%w)', function (c) return c:upper() end)
    return lowerCamelCase
end

Examples

GitHub via http

local Spore = require 'Spore'

local github = Spore.new_from_spec 'https://raw.github.com/SPORE/api-description/master/services/github.json'
github:enable 'Format.JSON'
github:enable('Auth.Basic', {
    username = 'schacon/token',
    password = '6ef8395fecf207165f1a82178ae1b984',
})
local res = github:get_info{format = 'json', username = 'schacon'}
print(res.status)               --> 200
print(res.headers['x-runtime']) --> 126ms
print(res.body.user.name)       --> Scott Chacon

GitHub via https

The HTTPS protocol requires LuaSec.

local Spore = require 'Spore'

local github = Spore.new_from_spec('https://raw.github.com/SPORE/api-description/master/services/github.json', {
    base_url = "https://github.com/api/v2/",
})
github:enable 'Format.JSON'
local res = github:get_info{format = 'json', username = 'schacon'}
print(res.status)               --> 200
print(res.headers['x-runtime']) --> 126ms
print(res.body.user.name)       --> Scott Chacon

CouchDB

This example comes from the book CouchDB, The Definitif Guide.

local base = 'https://raw.github.com/SPORE/api-description/master/apps/couchdb/'
local couchdb = require 'Spore'.new_from_spec(
    base .. 'server.json',
    base .. 'database.json',
    base .. 'document.json',
    base .. 'design.json',
    { base_url = 'http://127.0.0.1:5984/' })
couchdb:enable_if(function (req) return req.env.spore.caller ~= 'get_attachment' end, 'Format.JSON')

local r = couchdb:get_root()
print(r.body.couchdb)
print(r.body.version)

local r = couchdb:create_db{ db = 'albums' }
assert(r.body.ok)
local r = couchdb:create_db{ db = 'albums' }
print("error", r.body.error)
print("reason", r.body.reason)

local r = couchdb:add_document{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
    payload = {
        title = "There is Nothing Left to Lose",
        artist = "Foo Fighters",
    },
}
assert(r.body.ok)
print("id", r.body.id)
print("rev", r.body.rev)

local r = couchdb:get_uuids()
assert(#r.body.uuids == 1)
for i, v in ipairs(r.body.uuids) do print("uuid",i, v) end

local r = couchdb:get_document{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
}
print("_id", r.body._id)
print("_rev", r.body._rev)
print("title", r.body.title)
print("artist", r.body.artist)
local rev1 = r.body._rev

local r = couchdb:add_document{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
    payload = {
        title = "There is Nothing Left to Lose",
        artist = "Foo Fighters",
        year = 1997,
    },
}
print("error", r.body.error)
print("reason", r.body.reason)

local r = couchdb:add_document{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
    payload = {
        _rev = rev1,
        title = "There is Nothing Left to Lose",
        artist = "Foo Fighters",
        year = 1997,
    },
}
assert(r.body.ok)
print("id", r.body.id)
print("rev", r.body.rev)
local rev2 = r.body.rev

local r = couchdb:add_document{
    db = 'albums',
    id = '70b50bfa0a4b3aed1f8aff9e92dc16a0',
    payload = {
        title = "Blackened Sky",
        artist = "Biffy Clyro",
        year = 2002,
    },
}
print("Location", r.headers['location'])
assert(r.body.ok)
print("id", r.body.id)
print("rev", r.body.rev)

local slurp = require 'Spore.Protocols'.slurp
local r = couchdb:add_attachment{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
    rev = rev2,
    file = 'api.png',
    content_type = 'image/png',
    payload = slurp'api.png',
}
assert(r.body.ok)
print("id", r.body.id)
print("rev", r.body.rev)

local r = couchdb:get_attachment{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
    file = 'api.png',
}
print("Content-Type", r.headers['content-type'])
print("Content-Length", r.headers['content-length'])

local r = couchdb:get_document{
    db = 'albums',
    id = '6e1295ed6c29495e54cc05947f18c8af',
}
print("_id", r.body._id)
print("_rev", r.body._rev)
print("title", r.body.title)
print("artist", r.body.artist)
for k, v in pairs(r.body._attachments) do
    print(k)
    for kk, vv in pairs(v) do print(kk, vv) end
end

with Google & OAuth 1.0

This example uses the service Google URL Shortener.

local url = require 'socket.url'
local Spore = require 'Spore'
--Spore.debug = io.stdout

local function get_google_keys (scope, keys)
    local oauth = require 'Spore'.new_from_spec 'https://raw.github.com/SPORE/api-description/master/services/googleoauth.json'
    oauth:enable('Auth.OAuth', keys)
    local r1 = oauth:get_request_token{
        scope = scope,
    }
    print("request", r1.body)
    for k, v in r1.body:gmatch'([^&=]+)=([^&=]*)&?' do keys[k] = url.unescape(v) end

    local r2 = oauth:authorize_token{ oauth_token = keys.oauth_token }
    print("authorize", r2.status, r2.headers.location)

    os.execute("x-www-browser " .. r2.headers.location)

    print "enter oauth_verifier:"
    local input = io.stdin:read('*l')
    print("oauth_verifier=]" .. input .. "[")
    keys.oauth_verifier = input

    local r3 = oauth:get_access_token()
    print("access", r3.body)
    for k, v in r3.body:gmatch'([^&=]+)=([^&=]*)&?' do keys[k] = url.unescape(v) end

    keys.oauth_callback_confirmed = nil
    keys.oauth_verifier = nil
    return keys
end


local client = require 'Spore'.new_from_spec 'https://raw.github.com/SPORE/api-description/master/services/googleshortener.json'
client:enable 'Format.JSON'
client:enable('Auth.OAuth', get_google_keys('https://www.googleapis.com/auth/urlshortener', {
    oauth_consumer_key    = '000000000000.apps.googleusercontent.com',
    oauth_consumer_secret = 'XXXXXXXXXXXXXXXXXXXXXXXX',
}))

local r = client:insert{ payload = { longUrl = 'http://www.google.com/' } }
print(r.body.id, r.body.longUrl)

local r = client:list()
print "\nAUTHORIZED\n"
for k, v in pairs(r.body) do
    print(k, v)
end