API

The API is where you interact from other systems with binoas. You can send it new posts and add new subscriptions or detele them. General speaking the API is (somewhat) restful and data is generally accepted as a JSON payload.

Posts

POST /posts/new

This posts a new document to binoas. The payload is a JSON object, where only the application and payload keys are mandatory (other fields are ignored). The payload is a free form JSON dictionary.

Example:

POST /posts/new
{
  "application": "test"
  "payload: {
    "id": 1,
    "description": "This is a test with a few words",
      "topics': [
        {"id": 1, "name": "tag1"},
        {"id": 1, "name": "tag2"},
      ]
    }
  }
}

Response:

{
  "status": "ok"
}

Subscriptions

GET /subscriptions

GET /subscriptions

Available query parameters:

• user_id
• query_id
• frequency

Example call:

/subscriptions?user_id=81

Response:

{
  "meta": {
    "total": 1
  }, 
  "results": [
    {
      "description": "was", 
      "frequency": "1y", 
      "query_id": "cf02bf4e0244d168a6d94899f2c7d57442a1b735253faf235717cfeb", 
      "user_id": 81
    }
  ]
}

POST /subscriptions/new

This API call subscribes an email address with a search query to a specific application. The search query can be specified by either a subscription key (list of fields which results in an AND query) or by using a query key (which is an Elasticsearch specific query).

Fields:

• application (The application)
• email (the email address)
• frequency (expressed as short time descriptions, eg. 1200s for 20 minutes, 1y for 1 year etc.
• description (A humand readable description of the query)
• subscription/query (Specifies the search query).

Example with subscription key:

POST /subscriptions/new
{
  "application": "politwoops",
  "email":"[email protected]",
  "frequency': "6H",
  "description": "test",
  "subscription": {
    "title": "test"
  }
}

Example with query key:

POST /subscriptions/new
{
  "application": "politwoops",
  "email":"[email protected]",
  "frequency': "6H",
  "description": "test",
  "query": {
   "match": { "title": "test" }
  }
}

Returns:

{
  "status": "ok",
  "user": {
    "id": 81,
  },
  "query": {
    "id": "cf02bf4e0244d168a6d94899f2c7d57442a1b735253faf235717cfeb"
  }
}

DELETE /subscriptions/delete

DELETE /subscriptions/delete
{
  "user_id": 81,
  "query_id": "cf02bf4e0244d168a6d94899f2c7d57442a1b735253faf235717cfeb"
}

Returns:

{
  "status": "ok"
}