Line 71: Line 71:
 
|POST
 
|POST
 
||api/message/queue
 
||api/message/queue
 
 
||success or failure
 
||success or failure
 
||Adds a message to the queue. 50 messages are stored for every starling. This is handy to queue and display twitter feed. A message is picked from the queue every 2 minutes, displayed and deleted. The post data should contain the following
 
||Adds a message to the queue. 50 messages are stored for every starling. This is handy to queue and display twitter feed. A message is picked from the queue every 2 minutes, displayed and deleted. The post data should contain the following
Line 77: Line 76:
 
*message
 
*message
 
*source
 
*source
 
+
|-
 
+
|GET
 
+
||api/messages/{starling_id}
 +
||json array
 +
||Gets all messages stored for a particular starling
 
|}
 
|}

Revision as of 18:01, 31 December 2015

Authentication

Starling API works on javascript web-tokens. The default validity for the tokens is 1 year. It will be changed to shorter duration soon.

If you own a starling, create an account here.

Base URL for all requests: http://starling.exploreembedded.com

Obtaining the token

http verb Request Response Description
POST /api/authenticate token Pass email and password as body parameter to obtain a web token

Example with CURL

  • Request
curl -X POST -F "email=your@email.com" -F "password=password" \ 
'http://starling.exploreembedded.com/api/authenticate'
  • Response
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJzdWIiOiIyIiwiaXNzIjoiaHR0c
DpcL1wvc3RhcmxpbmcuZXhwbG9yZWVtYmVkasdfdsfNvbVwvYXBpXC9hdXRoZW50.
iwiZXhwIjoiMTQsdfeaeSEFEA0NiIsIm5iZiI6IjE0NTE1NjMwNDYiLCJqdGkiOiI4asdfew}
  • You may also use the postman client

example with postman

Starling device Registration and access

Every API request should include the token obtained above as a parameter in url or header.

http verb Request Response Description
GET /api/starlings returns all the starlings registered for the given user validates the user and returns any starlings registered in JSON
GET /api/starling/{id} returns a particular starling validates the user and returns the given starling data as JSON
PUT /api/starling/{id} edits a particular starling the parameter need to send as form or url encoded data
DEL /api/starling/{id} deletes the starling with the given ID use with caution
POST /api/starling pass the parameters in the form body Creates a new starling after validating the data

Messaging

Every API request should include the token obtained above as a parameter in url or header.

http verb Request Response Description
POST api/message/queue success or failure Adds a message to the queue. 50 messages are stored for every starling. This is handy to queue and display twitter feed. A message is picked from the queue every 2 minutes, displayed and deleted. The post data should contain the following
  • starling_id
  • message
  • source
GET api/messages/{starling_id} json array Gets all messages stored for a particular starling