External APIs
=============

Overview
++++++++

Authentication
--------------

Cureatr API can be accessed over HTTPS with Basic HTTP Auth (the Authentication header for the requests, very standard for REST-like API).

An API user id and an api key need to be provisioned for an organization to access the API.  To request API access, please contact your Client Services representative or support@cureatr.com .  You will need to provide the description of the API use case, a contact email for the API account, and a name for the account.

You can find the documentation on Basic HTTP Auth here: http://en.wikipedia.org/wiki/Basic_access_authentication#Client_side.  Note that Basic HTTP Auth requires the Api User ID and Api Key to be Base64 encoded in the Authorization header.

Parameters
----------

Some APIs require parameters to be passed using HTTP form data encoding, others require the parameters to be passed via raw JSON, and some support both forms.  Please look at the documentation and examples for guidance.

Responses
---------

Unless specifically indicated in the documentation, you can expect for all API calls to return JSON responses.

A valid API call will have an return code of **HTTP 200 OK**, and will contain a ``status`` key in the JSON response that indicates whether the operation completed successfully or not. 
 - ``status: ok`` indicates that the operation completed successfully
 - ``status: error`` indicates that an error has occurred, and additional information about the error is available under the ``message`` JSON key

Additionally, some reporting-type API calls may return **HTTP 204 No Content** to indicate that the response was blank because no results were produced

Invalid API calls may have one the following HTTP return codes
 - **400** - bad request; most likely the parameters don't conform to the specification
 - **401** - unauthorized; no valid authorization user id and key provided
 - **403** - forbidden; client can not perform requested action
 - **404** - not found; invalid API endpoint specified
 - **500** - internal error; should not be encountered during normal operation
 - **503** - service unavailable; API servers are over capacity, please retry later


Testing
-------

These API endpoints can be used to validate the API credentials and get familiar with parameters and responses

.. automodule:: api.controllers.api.util
    :members:


Example
-------

Creating a thread (via curl and pretty-printing the response with python)::

    curl -u $USER_ID:$API_KEY https://api.cureatr.com/api/2014-08-01/thread/create -d subject=hi -d patient_name=bob -d message=hey \
    -d recipients=foo@example.com -d recipients=bar@example.com -d recipients=baz@cureatr.com| python -m json.tool


API Modules
+++++++++++

User APIs
---------

.. automodule:: api.controllers.api.user
    :members:

Messaging APIs
--------------

.. automodule:: api.controllers.api.thread
    :members:

.. automodule:: api.controllers.api.message
    :members:

User Management APIs
--------------------

.. automodule:: api.controllers.api.admin
    :members: _create_user, _update_user, _find_user, users_list

Institution Management APIs
---------------------------

.. automodule:: api.controllers.api.institution
    :members:

Patient Management APIs
-----------------------

.. automodule:: api.controllers.api.patients
    :members:

.. autoclass:: cureatr.model.pii.PatientAttributes

Rx History APIs
-----------------------

.. automodule:: api.controllers.api.rx
    :members:

Pager Management APIs
-----------------------

.. automodule:: api.controllers.api.pager
    :members:

Recipient Group Management APIs
--------------------------------

.. automodule:: api.controllers.api.recipient_group
    :members: