1. Joe Wang Avatar Joe Wang
  2. Untitled project
  3. woomple

Wiki

Clone wiki

woomple / InternalAPI

View History

Internal API Specification

Current API version: 1

The base URL for all API methods is currently at http://api.woomple.com/v1/

Introduction

The Woomple API follows REST conventions and exchanges data in the JavaScript Object Notation (JSON) format.

Message API

The Woomple Message API provides a generalized data exchange mechanism between clients, servers, and backends.

message/send

Send a message for the server to process.

URL

http://api.woomple.com/v1/message/send

Supported Request Methods

POST

Parameters

An individual message is defined as

  • apiKey Required
    Unique key of current application using the API.
  • clientId Required
    Identifier of the unique device connecting to the server.
  • state
    A state variable that provides a context for the message.
  • type Required
    Data type of message. See server documentation for the types of data we support.
  • message
    Main data payload.

Response

Success
{
    "response": "ok"
}

message/retrieve

Retrieve any pending messages designated for a client.

URL

http://api.woomple.com/v1/message/retrieve

Supported Request Methods

GET

Parameters

  • apiKey Required
    Unique key of current application using the API.
  • clientId Required
    Identifier of the unique device connecting to the server.

Response

This is a sample response containing one pending message for the client. 

[{
    "type"    : "message",
    "message" :	"Hello World!"
}]

The server may produce three different types of messages to retrieve:

  • message
    A message to display to the user.
  • state
    A state change for the application.
  • poll
    A request to poll data from the client.

Rules API

The Woomple Rules API provides the ability to add or remove rules that govern a given application.

rules/add

Add a new rule.

URL

http://api.woomple.com/v1/rules/add

Supported Request Methods

POST

Parameters

The input data may be an array of individual rules. An individual rule is defined as

  • apiKey Required
    Unique key of current application using the API.
  • clientId
    JSON array of clientIds this rule should apply to. Top precedence (overrides groupId and groupType).
  • groupId
    JSON array of groupIds this rule should apply to. Second precedence (overrides groupType).
  • groupType
    Group Type that this rule should apply to.
  • events Required
    JSON array of BaseEvent JSON objects.
  • responses Required
    JSON array of Response JSON objects.
  • fulfillment Required
    Fulfillment JSON object.
  • persist
    Boolean of whether to persist this rule. Defaults to true.
  • persistTime
    If persist is false, this value determines how long to keep this rule from being fired.
BaseEvent

A BaseEvent can be either Event or EventGroup.

Event

An Event is defined as

  • jsonClass Required
    Must be set to the value Event
  • type Required
    Type of event. Can be one of text, double, accel, gps, or a custom type.
  • state
    State associated with the event.
  • cmp Required
    Comparison operator for the value.
  • value
    Value to compare.
EventGroup

An EventGroup is defined as

  • jsonClass Required
    Must be set to the value EventGroup
  • op Required
    Fulfillment JSON Object.
  • events Required
    JSON array of BaseEvent JSON objects.
  • within
    Integer value of seconds within which all the events in this group must be fulfilled. Defaults to 60.
Response

A Response can be either MessageClient or StateTransition.

MessageClient

An MessageClient is defined as

  • jsonClass Required
    Must be set to the value MessageClient
  • toSelf Required
    Boolean of whether to send this message to the client that triggered the action.
  • toGroup Required
    Boolean of whether to send this message to group(s) of the client that triggered the action.
  • toClients
    JSON array of clientIds to send the message to.
  • toGroups
    JSON array of groupIds to send the message to.
  • message
    Message payload to deliver.
StateTransition

An StateTransition is defined as

  • jsonClass Required
    Must be set to the value StateTransition
  • toSelf Required
    Boolean of whether to send this message to the client that triggered the action.
  • toGroup Required
    Boolean of whether to send this message to group(s) of the client that triggered the action.
  • toClients
    JSON array of clientIds to send the message to.
  • toGroups
    JSON array of groupIds to send the message to.
  • state
    State payload to deliver.

Response

Success
{
    "response": "ok"
}

rules/list

List all the rules currently in effect.

URL

http://api.woomple.com/v1/rules/list

Supported Request Methods

GET

Parameters

  • apiKey Required
    Unique key of current application using the API.

Response

Success
TBD

rules/delete

Delete a rule.

URL

http://api.woomple.com/v1/rules/delete

Supported Request Methods

GET

Parameters

The input data may be an array of individual rules. An individual rule is defined as

  • apiKey Required
    Unique key of current application using the API.
  • ruleId Required
    Unique identifier of rule to delete.

Response

Success
{
    "response": "ok"
}

Groups API

The Woomple Groups API provides the ability to manage logical groupings of clients.

group/add

Add a new group

URL

http://api.woomple.com/v1/group/add

Supported Request Methods

POST

Parameters

A group is defined as

  • apiKey Required
    Unique key of current application using the API.
  • type
    Group type.
  • clientIds
    JSON array of clientIds that belong to this group.

Response

Success
{
    "response": "ok",
    "groupId": "Stored Group ID"
}

group/modify

Modify group membership

URL

http://api.woomple.com/v1/group/modify

Supported Request Methods

POST

Parameters

  • apiKey Required
    Unique key of current application using the API.
  • groupId Required
    Group ID to update membership for.
  • clientIds Required
    JSON array of client IDs to either add or remove.
  • method Required
    Either addClients or removeClients.

Response

Success
{
    "response": "ok",
}

group/list

List all the groups according to filtering criterion

URL

http://api.woomple.com/v1/group/list

Supported Request Methods

GET

Parameters

  • apiKey Required
    Unique key of current application using the API.
  • type
    Filter by type.
  • clientId
    Filter by groups to which the client belongs.

Response

Success

This is a sample response containing one resulting group. 

[{
    "groupId"   : "theGroupID",
    "type"      : "Hello World!",
    "clientIds" : ["client1", "client2"]
}]

group/delete

Delete a group

URL

http://api.woomple.com/v1/group/delete

Supported Request Methods

POST

Parameters

  • apiKey Required
    Unique key of current application using the API.
  • groupId Required
    Group ID to delete.

Response

Success
{
    "response": "ok",
}

Clients API

The Woomple Clients API provides the ability to retrieve data about currently connected clients.

Updated