.. _http_api:

The HTTP API
============

Every refinery instance serves its complete API over HTTP, under the
``/api`` prefix. This is the very protocol the Python client speaks:
pointing ``timeseries()`` at an http uri yields the same api points
with the same semantics as a direct postgres uri (see
:ref:`API documentation`) — and it is also how federated instances
consume each other (see :doc:`security`).

Interactive reference
---------------------

The authoritative, always up-to-date endpoint reference is served by
the instance itself: browse ``https://<your-instance>/api`` for the
interactive (swagger) console, listing every endpoint with its
parameters, responses, and a try-it-out mode.

Speaking to it directly
-----------------------

Requests authenticate with a bearer token (see :doc:`security`). Most
endpoints speak plain json:

.. code:: bash

   $ curl -H "Authorization: Bearer $TOKEN" \
       'https://refinery.example.com/api/series/metadata?name=banana-spot-price'
   {"unit": "eur", "source": "market"}

The series *values* endpoints (``/series/state``, ``/series/history``
and friends) return a compact binary encoding rather than json: they
are designed for the Python and Excel clients. For scripted access to
the values, prefer the Python client over an http uri:

.. code:: python

   from tshistory.api import timeseries
   tsa = timeseries('https://refinery.example.com/api')
   ts = tsa.get('banana-spot-price')