blink(1) Web Service Reflector for IFTTT   
========================================
20121121 tod at thingm.com

Intro
-----

The blink(1) event web service lives at:

    http://api.thingm.com/blink1

It is used for an external web-based service (like IFTTT) to post events to be 
consumed by blink(1).  These events contain a color pattern name for blink(1) 
to play and the source of the event.


Events
------
Events are comprised of the attributes:

- blink1_id -- UID of user's blink1 + computer, as 16-digit hex string
- name      -- rule name of event, (e.g. "New mail from Fred", or "it's raining"), as string
- source    -- data source of event (e.g. "gmail","twitter"), as string
- date      -- date event occurred, as secs since unix epoch, as string

Two kinds of event submission are supported: 

- single event, real-time
- event bundle, of recent past events (e.g. last 15 minutes)


Single Event Submission
------------------------
base URL: `http://api.thingm.com/blink1/sendevent/{blink1_id}`

method: GET 

Query argument parameters:

- name - Rule name of event, can be based on IFTTT recipe name, etc.
- source - IFTTT event source designator (e.g. Gmail, Twitter)

Example GET: 

   `/blink1/sendevent/23049309b33ab3cd/?name=flash_red&source=gmail`

Example result:

    {
      "blink1_id":"23049309b33ab3cd",
      "name":"new mail",
      "source":"gmail",
      "date":"1348610490",
      "status":"success: event saved"
    }


Multilple Event Submission
--------------------------
base URL: `http://api.thingm.com/blink1/sendevents/{blink1_id}`

method: POST  

Query arguments: none

POST body format: JSON array of events named "events".

Example POST:

    /blink1/sendevents/23049309b33ab3cd

POST body:

    {
     "events": [ 
      { 
        "blink1_id": "23049309b33ab3cd",
        "date": 1348547434,
        "name": "ladygagatweet",
        "source": "twitter"
       },
       { 
        "blink1_id": "23049309b33ab3cd",
        "date": 1348547454
        "name": "important message",
        "source": "gmail"
       }
      ]
    }

Example result:
    { 
      "status": "events received",
      "event_count": 2,
      "blink1_id": "23049309b33ab3cdef"
    }



Retrieving events
-----------------
To retrieve events you must have a valid blink1_id that has had events
sent to it already.

base URL: `http://api.thingm.com/blink1/events/{blink1_id}`

method: GET

Query arguments: none

Example GET:

    http://api.thingm.com/blink1/events/4428808301AA1A23

Example result:

    {
      "events":[
        {
          "blink1_id":"4428808301AA1A23",
          "name":"new mail",
          "source":"gmail",
          "date":"1348631098"
        },
      ],
      "event_count":1,
      "status" : "ok"
    }



-eof-