NAV Navbar
http

Introduction

Blip is a mobile connectivity platform that enables mobile devices to asynchronously connect to host application via passive blip points. A mobile device is regarded as client and the host is most commonly any kind of back-end service.

Blip overview

The Blip points are designed and distributed by Ifdef for solution providers. Host and client applications can subscribe to blip points to create data channel between them when applicable.

The following documentation describes the API and flow of the Blip mobile connectivity platform.

Actions

Each Blip point has one action connected to it that determines what to do on a tap event.

The action is determined by the tag owner (host) and the first thing the client should do on a tap is to check the action.

Fetch

Static data is stored for the tag and sent to the client upon a tap. The data on the tag can be updated at any time by the host.

Example data stored on a tag

{
  "ns": "ifdef.blip.fetch.example",
  "data": {
    "foo": "bar"
  }
}

The data stored on the tag is on the following format

key type value
ns string The namespace identifing this type of data
data json data object stored on the tag

Channels

Data connection will be opened between the client and host where data can be exchanged between host and client.

The connection is initiated from the host and kept alive until the host closes it.

Example message sent using CHANNEL connection

{
  "ns": "ifdef.blip.channel.example",
  "data": {
    "foo": "bar"
  }
}

All messages sent should be on the following json format

key type value
ns string The namespace identifing this type of message
data json data object sent from host/client

Host API

Authentication

In order to interact with blip api , an authentication token is needed in the header of all requests. The token is distributed by Ifdef.

To call an endpoint you need to add the following headers:

GET /blip/v1/<endpoint> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io

Make sure to replace <token> with your API key.

To use the Blip API the following headers must be added to every API call.

Header Value Description
Authorization Bearer <token> Your private API key that identifies you.
Content-Type application/json Blip API is JSON based.

Update Tag Information

PUT /blip/v1/tag/<id> HTTP/1.1
Content-Type: application/json
Authorization: apikey <token>
Host: https://api.ifdef.io

{
    "action": "FETCH",
    "ns": "io.ifdef.blip.example.fetch",
    "data": {
        "foo": "bar"
    }
}
PUT /blip/v1/tag/<id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io

{
    "action": "CHANNEL",
    "ns": "",
    "data": {}
}

The following is a successful response to these PUT requests

HTTP/1.1 200 OK

This endpoint updates the action, ns and data on the tag.

HTTP request

PUT /blip/v1/tag/<id>

URL Parameters

Key Type Description
id string The id of the tag.

Body

Key Type Required Description
action string Y The action connected to the tag.
ns string N Identifier for the data field.
data json Y-N Data stored on the tag (Required for action "FETCH").

Channels

A channel is initiated when the host subscribes to the client data. On a successful subscription a Session-ID is received and that Session-ID has to be used for all subsequent communication to that channel instance. A channel instance is closed when the host terminates the connection.

Open channel

Example of a GET request initiating a new channel

GET /blip/v1/host/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io
HTTP/1.1 200 OK
Session-ID: <sid>

GET /blip/v1/host/<tagid>

By sending a get request to the endpoint a channel is created given that no channel already exists for the tag. If this is a new channel the GET request immediately returns and the Session-ID can be read from the headers.

Upon receiving the Session-ID a new GET request should be sent using the Session-ID, that request will return with data from the other end or timeout after 60 seconds

It is the responsibility of the host to send a new GET request upon timeout or receiving data to maintain the channel.

Send data

Send data through the channel using POST request

POST /blip/v1/host/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io

{
    "ns": "ifdef.blip.example.channel.post",
    "data": {
        "foo": "bar"
    }
}

Successful response to the POST request

HTTP/1.1 200 OK
Session-ID: <sid>

Data can only be sent after a channel is started and a Session-ID has been received.

Make a normal http POST request with the Session-ID and Bearer tokens in the header.

POST /blip/v1/host/<tagid>

Close channel

Close down a channel

DELETE /blip/v1/host/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Session-ID: <sid>
Host: https://api.ifdef.io

Successful response to the DELETE request

HTTP/1.1 200 OK

DELETE /blip/v1/host/<tagid>

The host can close the channel immediately by sending a DELETE reguest using the tagid.

The Session-ID and Authentication token need to be given in the header.

Client API

Authentication

Endpoints for the Client API are unauthenticated, thus no additional headers are needed.

Fetch Tag Information

GET /blip/v1/tag/<id> HTTP/1.1
Host: https://api.ifdef.io

The following is a successful response to these GET requests

HTTP/1.1 200 OK
{
    "action": "FETCH",
    "ns": "io.ifdef.blip.example.fetch",
    "data": {
        "foo": "bar"
    }
}
HTTP/1.1 200 OK
{
    "action": "CHANNEL",
    "ns": "io.ifdef.blip.example.channel",
    "data": {}
}

This endpoint retrieves the action, ns and data on the tag.

HTTP request

GET /blip/v1/tag/<id>

URL Parameters

Key Type Description
id string The id of the tag.

Body

Key Type Required Description
action string Y The action connected to the tag.
ns string N Identifier for the data field.
data json Y-N Data stored on the tag (Required for action "FETCH").

Channels

The client can communicate with the host when the host has initiated a channel. On a successful subscription a Session-ID is received and that Session-ID has to be used for all subsequent communication to that channel instance. A channel instance is closed when the host terminates the connection.

Open channel

Example of a GET request connecting to a channel

GET /blip/v1/client/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io
HTTP/1.1 200 OK
Session-ID: <sid>

GET /blip/v1/client/<tagid>

By sending a get request to the endpoint the client connects to a channel given that it has been created by a host. The Session-ID can be read from the headers.

Upon receiving the Session-ID a new GET request should be sent using the Session-ID, that request will return with data from the other end or timeout after 60 seconds

It is the responsibility of the host to send a new GET request upon timeout or receiving data to maintain the channel.

Send data

Send data through the channel using POST request

POST /blip/v1/client/<tagid> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Host: https://api.ifdef.io

{
    "ns": "ifdef.blip.example.channel.post",
    "data": {
        "foo": "bar"
    }
}

Successful response to the POST request

HTTP/1.1 200 OK
Session-ID: <sid>

Data can only be sent after a the client has connected and received a Session-ID.

Make a normal http POST request with the Session-ID in the header.

POST /blip/v1/client/<tagid>

Examples

Flowchart describing roll out of tags and different interactions.

Blip overview