Tranquil APIs

v0.1

Nick Moore <nick@mnemote.com>

Tranquil APIs

• Protocol Framework
• Tranquil is similar in intention to REST
• Transport agnostic.
• Allows multiple 'actions' per request.
• Actions are composable and extensible.
• Doesn't have horrible URLs?filter_name=Nick&$format=json

Tranquil: Contexts

A context describes a group of resources.

• “all users”
• “all active users”
• “all users over 35”
• “all contacts for user number 12345”

Tranquil: Actions

• actions transform contexts into other contexts
• ... OR into data which is returned in the response.

For example, the “all users” context could be transformed into the “users over 35” context using a “filter” action.

Tranquil: Composing Actions

Action Lists

Builds a pipeline of actions

[ [ "filter", { "is_author": true } ], "count" ]

Action Groups

Labels actions and runs them in parallel

{
    "count": "count",
    "page": [ [ "page", 0, 5 ] ]
}

Tranquil: Composing Actions

{
    "authors": [
        "users",
        [ "filter": { "is_author": true } ],
        {
            "count": "count",
            "top10": [
                [ "sort", "-score" ],
                [ "page", 0, 10 ]
            ]
        }
    ]
}

Tranquil: Composing Actions

{
    "authors": {
        "count": 23,
        "top10": [
            { "name": "Fred Nerk", ... },
            { "name": "Joe Blow", ... },
            ...
        ]
    }
}

Tranquil: HTTP Transport

POST /api
Content-Type: application/json
Accept: application/json

{ "user_count": [ "users", "count" ] }

200 OK
Content-Type: application/json

{ "user_count": 107 }

Transport Agnostic

More!

• http://nick.zoic.org/etc/tranquil-apis/
• Tonight's BOF