General information
===================


API versioning and future-proofing
----------------------------------

.. important:: Clients should always be prepared to receive more information
  than documented here (e.g. *additional* properties in returned JSON documents
  or equivalent).

Please also note that all APIs are versioned individually in order to avoid unnecessary
churn in clients. Old API versions may no longer be mentioned in this documentation
but will continue to work until further notice. We generally recommend switching to
the most recent version when possible.


Error handling
--------------
APIs will generally return an http 2xx status code on success and a response body as
documented for the respective API (usually a json document with an object at the top level).
Note that `success` in this case simply means that the API call was performed correctly,
please refer to the respective APIs documentation on how to interpret the
response.

As most APIs require authentication via an oauth2 access token a response with
status code 401 is of special interest. This status code indicates that the
client did not provide a valid access token (e.g. when the token expired, user
logged out, …).
Applications should then obtain a fresh access token and retry the request.

Unless otherwise noted in the APIs documentation, any other status code should be treated as an error.

.. note:: Error responses usually contain a body with more details to aid
   debugging. This is only intended for human consumption and must not be
   relied on by applications as it's presence, format and content may change at
   any time.


Glossary
--------
.. glossary::

  channel
    Channels give access to manufacturer catalogs and applications.
    Access is requested and granted for each channel separately allowing e.g. the use of
    a different distribution region.