Push API

Locker core has native support to have data pushed into it and stored using a very simple pattern. This is useful for external sources of data that can trigger custom POST requests to the private url for a locker, no connector/synclet code is needed, yay! Relevant code: https://github.com/LockerProject/Locker/blob/master/Ops/webservice-push.js

URI

The private URL to push into the locker must be known or configured in some way already, if the push request is happening on localhost (from a browser to a locally running locker) it would be

http://localhost:8042/push/:id

On a Singly hosted locker, it would be

https://me.singly.com/:private-hash-token/push/:id

ID

The :id used above must be unique to the application or service, anything can be chosen but try to not use a really generic one and keep it specific to the data being pushed. For instance, a chrome browser history extension could use an id of "chromehistory" safely.

POST Content-Type

application/json

POST Body Example

{
    "data": [
        { "id": "service-specific-unique-identifier", ... },
        { "id": "service-specific-unique-identifier2", ... },
        { "id": "service-specific-unique-identifier3", ... }
    ],
    "config":{ }
}

By POSTing to the /push/:id endpoint a JSON object formatted like above, each entry in the data array will be processed, stored, and generate data events within the locker. Any existing matching id's per object will be replaced by the new one. The config object is merged with any existing one or saves this one, and can be retrieved (see below) to get a last-known state before pushing.

Retrieving Pushed Data

GET /push/:id/getCurrent -- returns all in an array (could be large, can use limit=x&offset=y)
GET /push/:id/:service-specific-unique-id -- returns json object that was pushed under that id, if any

Curl examples

curl --data-binary '{"data":[{"id":42}]}' http://localhost:8042/push/foo -H "Content-Type: application/json"
ok

curl http://localhost:8042/push/foo/42
{"_id":"4f2752c03f670f3343f7fed0","id":42}