Indivo Experimental APIs
========================

The Indivo experimental APIs are used to evaluate new potential features. They are not guaranteed to be supported, 
consistent, or used in production. When an API is experimental, it is under the ``/experimental/`` URL base. An 
API graduates to full support by being moved into the normal tree of API URLs, which requires a change in all clients 
that implement it. This is done on purpose: to ensure that experimental APIs cannot be depended upon, ever, until they 
graduate to full support.

PubSub
------

*Status*: first design, **no implementation**

Applications may want to be notified of changes that occur in the record, so they can take action without having to 
constantly poll the Indivo server. We call these subscriptions.

Add a subscription
^^^^^^^^^^^^^^^^^^
::

  POST /experimental/records/{record_id}/apps/{pha_email}/subscriptions/
  url={url}&
  callback={callback_url}

  <Subscription id="..." />

A subscription is created by an app on a specific URL, within a record. The URL is relative to the record, i.e. ``/reports/minimal/medications/``. For now only report URLs are supported.

The callback URL is the URL that Indivo should connect to when an update pertaining to that subscription occurs. 

View subscriptions
^^^^^^^^^^^^^^^^^^
::

  GET /experimental/records/{record_id}/apps/{pha_email}/subscriptions/

  <Subscriptions>
    <Subscription id="..">
      <expires_at>...</expires_at>
      <url>...</url>
    </Subscription>
  </Subscriptions>


A subscription lasts 3 months by default, and then automatically expires and must be renewed.

Remove subscription
^^^^^^^^^^^^^^^^^^^
::

  DELETE /experimental/records/{record_id}/apps/{pha_email}/subscriptions/{subscription_id}

Behavior of a subscription ping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When an app is to be notified of a change, if, for example, that app subscribes to medications, then a new medication 
would trigger::

  POST <callback_url>
  record_id={record_id}&
  url={url}

Pings based on a subscription are expect a 200 successful HTTP code. If they receive a 500 or other error code, 
the ping will be tried again with exponential backoff, using 1 minute as initial retry interval, and a factor of 2 
between retries.