Mspecs API


PUSH SUBSCRIPTIONS API
The following describes how the push subscriptions work.

The push interface allows events that happen to the DB to be pushed to
a specific URLs. This makes it possible for external applications to
listen to events that fire in the system. It is possible to specify
what should be pushed by limiting what triggers a specific push
subscription.


PUSH PREREQUISITES

Preconditions for using the push functionality are
  that the organization subscribes to the push functionality,
  that the organization subscribes to the (full) API, and
  that the organization's default pushSubscriptionURL is set.

The default pushSubscriptionURL is used as a fallback receiver for all
push subscriptions that trigger and do not specify a pushURL. Use the
API to PUT a string URL into the pushSubscriptionURL (max 200
characters) on the organization to set the default.

The full API allows the license sevices to enable push subscriptions
for the organizaton (organizations.enablePushSubscription). Contact
license services at license@mspecs.se if you want to order the full
API.

Example

In the examples we will store the credentials of the user in the shell
variable USPA and the address of the API server in SERV. This will
make the curl commands shorter without hiding anything vital. (In bash
we can set the varables with USPA=user:pass and
SERV=https://api.mspecs.se)

First we just want to get the ID of the organization we are going to
update (we also ask for the pushSubscriptionURL to see if it is set),
then we use that id in a request to set the default URL. The setting
will return the new data for the organization so we can immediately
check that the URL was set ok. (There are omitted lines in the
returned data for the organization.)

$ curl -k -u$USPA $SERV/organizations?fields=id,pushSubscriptionURL
[
  {
    "id": "MDAtMXwwMDAwMDAwMDAwMnwx",
    "pushSubscriptionURL": null
  }
]
$ curl -k -u$USPA -d'pushSubscriptionURL=https://127.0.0.1:9082/' $SERV/organizations
{
  "id": "MDAtMXwwMDAwMDAwMDAwMnwx",
  ...
  "pushSubscriptionURL": "https://127.0.0.1:9082/",
  ...
}

REGISTERING A PUSH SUBSCRIPTION

All management of subscriptions for push events is done using the API
and the table that manages the subscriptions is called pushSubscriptions.

Subscriptions are set up specializing entries in the pushSubscriptions
table. Entering more information into a subscription will limit what
subscription will trigger on. Once added a subscription will start
monitoring the event stream to see if it triggers.

The available fields for specialization are:
 eventUserAccountId  set to a userAccount monitor that user
 eventKind           ADD | UPDATE | DELETE set to limit to just this
 eventTable          the table monitored (MANDATORY)
 eventId             only trigger events regarding the given id
 eventField          select a field required in the event to trigger
 pushURL             override the organization's pushSubscriptionURL

Note that even if an event triggers several subscription, only one
event will be sent to each distinct URL! How this works will be shown
below.

Note that if a eventField is set only the UPDATE eventKind is usefull
and can this be omitted.


Further examples:

If we want to subscribe to all changes to the deals table, we simply
add a subscription with only eventTable set to "deals". Then we create
a new deal just to see if we get a push to the default URL (which was
set above).

$ curl -k -XPOST -u$USPA -d'eventTable=deals' $SERV/pushSubscriptions
$ curl -k -XPOST -u$USPA -d'displayName=pushTest1' $SERV/deals
{
  "id": 'MDAwMnwwMDAwMDAwMDAwNHw1OA..',
  ...
  "displayName": "pushTest1",
  ...
  "updatedDate": "2016-01-27T14:05:26.000Z"
}

The push server should have received the push with a body like:

{ userAccountId: 'MDAtMXwwMDAwMDAwMDAwMnw0',
  eventKind: 'ADD',
  eventTable: 'deals',
  eventId: 'MDAwMnwwMDAwMDAwMDAwNHw1OA..',
  eventData:
   { id: 'MDAwMnwwMDAwMDAwMDAwNHw1OA..',
     ...
     displayName: 'pushTest1',
     ...
     updatedDate: '2016-01-27T14:05:26.000Z' },
  timestamp: '2016-01-27 14:05:26',
  sourceIp: '127.0.0.1',
  pushUrl: 'https://127.0.0.1:9082/' }

and headers like:

{ 'x-push-id': '1',
  'content-type': 'application/json',
  host: '127.0.0.1:9082',
  accept: 'application/json',
  'content-length': '4077',
  connection: 'close' }

Description of the fields in the pushed event:
 userAccountId   the account that triggered the push event
 eventKind       as above
 eventTable      as above
 eventData       stripped data of the event
 timestamp       timestamp in the DB (UTC)
 sourceIp        IP from which the event originated
 pushUrl         the URL this was sent to


If we want to only subscribe to when estates are deleted, eventTable
should be set to "estates" and eventKind set to "DELETE".

$ curl -k -XPOST -u$USPA -d'eventTable=estates&eventKind=DELETE' $SERV/pushSubscriptions
{
  "id": "MDAwMnwwMDAwMDAwMDAwM3w2Nw..",
  ...
  "propertyName": "pushTestEstate",
  ...
  "updatedDate": "2016-01-27T15:22:07.000Z"
}

At this time nothing will be pushed as there is no subscription to
trigger a push. So we continue and delete the estate which will result
in a push.

$ curl -k -XDELETE -u$USPA $SERV/estates/MDAwMnwwMDAwMDAwMDAwM3w2Nw..
$

and the push body will be:

{ userAccountId: 'MDAtMXwwMDAwMDAwMDAwMnw0',
  eventKind: 'DELETE',
  eventTable: 'estates',
  eventId: 'MDAwMnwwMDAwMDAwMDAwM3w2Nw..',
  eventData: {},
  timestamp: '2016-01-27 15:25:16',
  sourceIp: '127.0.0.1',
  pushUrl: 'https://127.0.0.1:9082/' }

and its header:

{ 'x-push-id': '2',
  'content-type': 'application/json',
  host: '127.0.0.1:9082',
  accept: 'application/json',
  'content-length': '244',
  connection: 'close' }


Now we want to add a specific push for when deals are deleted, so we
first add a new subscription and then we delete a deal to get the
pushes.

$ curl -k -XPOST -u$USPA -d'eventTable=deals&eventKind=DELETE&pushURL=https://127.0.0.1:8092/dealDeleteRcvr' $SERV/pushSubscriptions
{
  "id": "MDAwMnwwMDAwMDAwMDAwNHwxNzU.",
  "eventUserAccountId": null,
  "eventKind": "DELETE",
  "eventTable": "deals",
  "eventId": null,
  "eventField": null,
  "pushURL": "https://127.0.0.1:9082/dealDeleteRcvr",
  "updatedDate": "2016-01-27T15:38:10.000Z"
}
$ curl -k -XDELETE -u$USPA $SERV/deals/MDAwMnwwMDAwMDAwMDAwNHw1OA..
$

This will actually result in that two pushes are sent, one to the
default pushSubscriptionURL and one to the subscription specific URL
in the rule just added:

{ userAccountId: 'MDAtMXwwMDAwMDAwMDAwMnw0',
  eventKind: 'DELETE',
  eventTable: 'deals',
  eventId: 'MDAwMnwwMDAwMDAwMDAwNHw1OA..',
  eventData: {},
  timestamp: '2016-01-27 15:54:51',
  sourceIp: '::ffff:127.0.0.1',
  pushUrl: 'https://127.0.0.1:9082/' }
{ 'x-push-id': '13',
  'content-type': 'application/json',
  host: '127.0.0.1:9082',
  accept: 'application/json',
  'content-length': '242',
  connection: 'close' }

and:

{ userAccountId: 'MDAtMXwwMDAwMDAwMDAwMnw0',
  eventKind: 'DELETE',
  eventTable: 'deals',
  eventId: 'MDAwMnwwMDAwMDAwMDAwNHw1OA..',
  eventData: {},
  timestamp: '2016-01-27 15:54:51',
  sourceIp: '::ffff:127.0.0.1',
  pushUrl: 'https://127.0.0.1:9082/dealDeleteRcvr' }
{ 'x-push-id': '13',
  'content-type': 'application/json',
  host: '127.0.0.1:9082',
  accept: 'application/json',
  'content-length': '256',
  connection: 'close' }

So, mind that the rule is that pushes will be sent only once to each
URL, not to each site.

Tables typically of interrest to get pushes about are deals, estates
and bids. Though possible, it is more complicated to get pushes when
adding images to a specific deal, involving setting more fields in the
subscription. But, the are also other ways uf getting informed when
things change, like publishing data to a company specific web.