REST API
========

The REST API is only available on TeamHub :doc:`Pro <plans>`.

Endpoints
---------

We have the following API endpoints exposed.

Base URL: https://api.teamhub.co.za/v1

+------------+--------+----------------------------------------------+----------------------------+---------------+
| Endpoint   | Verb   | URL Params                                   | Example                    | Rate Limit    |
+============+========+==============================================+============================+===============+
| /balances  | GET    | - date                                       | /balances?date=2019-06-30  | Once per hour |
|            |        |                                              |                            |               |
|            |        |   - Format: YYYY-MM-DD                       |                            |               |
|            |        |   - Optional, defaults to current month end  |                            |               |
+------------+--------+----------------------------------------------+----------------------------+---------------+

API Key
-------

Please contact :doc:`support`

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

Ensure any requests have a header with your API Key supplied

.. code-block:: none

    Authorization: Bearer <ApiKey>

Example:

.. code-block:: none

    Authorization: Bearer c62f64fa2411408ab668a49896b42840

Rate Limiting
-------------

You will receive error code HTTP 429 (Too Many Requests) if you exceed the rate limits in place per endpoint.

NB: Do not abuse this API and apply a `practical <https://en.wikipedia.org/wiki/Exponential_backoff>`_ retry / timeout mechanisms.

Examples
--------

Query:

.. code-block:: bash

    curl -H "Authorization: Bearer c62f64fa2411408ab668a49896b42840" -X GET https://api.teamhub.co.za/v1/balances

JSON Result:

.. code-block:: json

    [
      {
        "id": "XXonp9ChrA4BFjqeP",
        "name": "Name Surname",
        "username": "user@example.com",
        "balances": [
          {
            "type": "A9GuNtJxXFt5iwm9J",
            "name": "Annual 20",
            "days": "10.0000",
            "date": "2019-05-31"
          },
          {
            "type": "AykgzKdGDPCaEaMjC",
            "name": "Sick",
            "days": "28.0000",
            "date": "2019-05-31"
          },
          {
            "type": "AiXw5DsXkyaLKgCRh",
            "name": "Study",
            "days": "5.0000",
            "date": "2019-05-31"
          },
          {
            "type": "AMscSqmGGSjBT4P4E",
            "name": "Unpaid",
            "days": "-2.0000",
            "date": "2019-05-31"
          }
        ]
      },

      .
      .
      .
    ]