API

API 2014

Request/Response JSONRPC 2.0

---> request

{
  "id": "<uuid>",
  "method": "<object.verb>",
  "params": { 
    "<object attribute>": { "<type>" : { "id":123, "<attr2>":"<value>"} },
    "<location>": { "location" : { "id":456, "latitude": 45.5 } }
  }
}

<--- respond

{
  "id": "<uuid from request>",
  "result": {
    "result param 1": "value 1"
  }
}

<--- receive on error

{
  "id": "<uuid from request>",
  "error": {
     "code": "<code>",
     "message": "<human readable message>"
  }
}

Endpoint

• wss://api.icecondor.com/v2

Type: hello

Hello is the first message to be sent and received on the stream.

<--- server hello

{
  "id" : "<uuid>",
  "method": "hello",
  "params": {
    "name" : "<server name>",
    "version": "<software version>",
    "session_id": "<session id>"
  }
}

---> client hello (not used)

{
  "id": "<uuid>",
  "method": "hello",
  "params": {
    "version": "<version id>"
  }
}

<--- receive

{
  "id": "<uuid>",
  "result": {
  }
}

Type: auth.email

Request a session token be sent to the email

---> client request

{
  "id": "<uuid>",
  "method": "auth.email",
  "params" : {
    "email": "<email>",
    "device_id": "<device id>"
  }
}

<--- receive

{
  "id": "<uuid>",
  "result": {
    "status": "sent"
  }
}

{
  "id": "<uuid>",
  "error": {
     "code": "<code>",
     "message": "Unsuccessful token request."
  }
}

Token

icecondor://android/v2/auth?access_token=<token>

Picked up by AndroidManifest

<data android:scheme="icecondor" />

Type: auth.session

The api stream starts out as unauthenticated. Some commands do not need authentication. The device key is the base64(sha256.hex(access_token+device_id))

---> client request

{
  "id": "<uuid>",
  "method": "auth.session",
  "params" : {
    "device_key": "<device key>",
  }
}

<--- receive

{
  "id": "<uuid>",
  "result": {
  }
}

{
  "txid": "<uuid>",
  "error": {
     "code": "<code>",
     "message": "Unsuccessful authentication."
  }
}

Type: location.create

A location message can come from the client to record a new position. It can also come from the server to the client to report a historical position. ---> send

{
  "id": "<uuid>",
  "method": "location.create",
  "params": {
      "position" : {
        "latitude" : 45.5,
        "longitude" : -122.5,
      },
      "provider": "gps"
  }
}

<--- receive

{
  "txid": "<uuid>",
  "result": {
    "ok": true
  }
}

{
  "txid": "<uuid>",
  "error": {
     "code": "<code>",
     "message": "<human readable message>"
  }
}

Type: device.create

{ "id": "<txid>",
  "method": "device.create",
  "params": {
    "device_id": "<device_id>",
    "client" : {
      "name" : "icecondor",
      "version" : "20111010",
    },
    "platform" : {
      "name" : "android",
      "version" : "2.3"
    },
    "hardware": {
      "make": "LG",
      "model": "ab-201"
  }
}

Future work

Streaming Filter

The client sends a filter message to begin a stream of Nouns from the server (such as location).

stream

{ "type": "stream",
  "noun": "location"
  "filters": [ <filter elements> ]
}

Filter elements

Filter on username

  { "type":"user", "username": "donpdonp"}

Filter on bounding box

  { "type":"boundingbox", "geometry" : 
                      {"type": "Polygon",  "coordinates": []} }

Admin

stats

{ "type": "status",
}