General information
===================
Unless otherwise noted requests must be authenticated with a bearer token obtained via
OAuth2 from pCon.login and include the ``query_account`` or ``query_receivable_pud_update_channels``
scope (see `OAuth2 scopes <https://login.pcon-solutions.com/doc/api/oauth2.html#scopes>`_)


Query users package groups
==========================
Query the package groups available to the user.

::

  GET /api/v1/get_package_groups
  Authorization: Bearer aabbccddee1122

  ==>

  {
    "has_update_channel" : true,
    "package_groups" : [
      {
        "name" : "ANY",
        "provider" : "emat_materialien",
        "uuid" : "b8c48fdf-059c-4454-8555-205862af6ba6"
      }
      {
        "name" : "TEST",
        "provider" : "test_provider",
        "uuid" : "93f717fe-0da0-401d-8b57-babb1ee9b9cc"
      }
    ]
  }

Response
--------
The response is a json document with the following properties

:has_update_channel:
  Boolean, indicates whether the use has at least one update channel.
  If this is false either the organization has not requested access to catalogs yet,
  or the user was not assigned to an appropriate channel.
  In either case the user should contact the organization's
  `administrator <https://login.pcon-solutions.com/doc/api/account.html#get-administrators-of-the-user>`_
  to get catalog access set up.

:package_groups:

   List of all package groups the user has access to.
   Each is represented by an object with these properties:

   :uuid: UUID of the package group
   :provider: Name of the provider this group belongs to
   :name: Name of the package group

  .. note:: Only the ``uuid`` should be used for further processing, the ``provider`` and ``name`` fields
     are only inteded as aid for debugging issues with wrong or incomplete package group assignments


Currently it is not possible to combine data from more than one channel
In case of misconfiguration the application will receive an error response
with status code 403, and the property `error = "too_many_update_channels"` and the json body

::

  GET /api/v1/get_package_groups
  Authorization: Bearer aabbccddee1122

  ==>
  HTTP/1.1 403 Forbidden
  Content-type: application/json

  {
    "error": "too_many_update_channels",
    "message": "... some description here ...",
    "troubleshooting_url": "https://login.pon-solutions.com/organization/channels"
  }

If present the property `troubleshooting_url` points to an url where the user
can find additional information on how to resolve the issue.
Applications should therefore display this url in their corresponding error dialog.

As usual, additional properties may be present in the body.
Please also note that the `message` property (if present) is only intended as
debugging aid for developers and not suitable for display to end users.


Query accessible manufacturers
==============================
Query the OFML manufacturers the user can access.

::

  GET /api/v1/account/approved_manufacturers
  Authorization: Bearer aabbccddee1122

  ==>

  {
    "manufacturers" : ["egr", "ofml", "xyx"]
  }

Response
--------
The response is a json document with the following properties

:manufacturers: List of OFML manufacturers the user can access


Query all manufacturers
=======================
Query all OFML manufacturers currently on the server.

.. note:: This API is only available for users with a special permission (`pcon_update_get_all_manufacturers`).

::

  GET /api/v1/all_manufacturers
  Authorization: Bearer aabbccddee1122

  ==>

  {
    "manufacturers" : ["egr", "ofml", "xyx"]
  }

Response
--------
The response is a json document with the following properties

:manufacturers: List of OFML all manufacturers currently on the server


Query publicly visible providers
================================
Returns a list of all publicly available providers.

::

  GET /api/v1/providers/list?lang=en


  {
      "providers" : [
          {
              "display_name" : "Example Provider",
              "filter_values" : {
                  "country" : ["DE", "GB"]
              },
              "id" : 12345,
              "info" : {
                  "url" : "https://example.com/"
              },
              "logo" : "https://update.easterngraphics.com/xus/image_cache/be81912aa5a89fa4890e3adc8ce573c8774c2a8c7a78ad5c02e7a059fe31f707.svg",
              "name" : "xyz_example",
              "public_since" : "2017-01-23T14:01:55+00:00"
          }
      ],
      "filters" : [
          {
              "name" : "country",
              "text" : "Availability",
              "values" : [
                  {
                      "name" : "AD",
                      "text" : "Andorra"
                  },
                  {
                      "name" : "AE",
                      "text" : "United Arab Emirates"
                  },
                  ...
              ]
          },
          {
              "name" : "language",
              "text" : "Data language",
              "values" : [
                  {
                      "name" : "de",
                      "text" : "German"
                  },
                  ...
              ]
          },
          ...
      ]
  }


Parameters:
-----------

:lang: Language code to be used for texts in the response


Response:
---------
The response is a json object with the following properties

:providers: List of provider items, each containing these properties:

    :display_name: Name of the provider, suitable for display to the user
    :name: Name of the provider in the system
    :id: Unique id of the provider
    :logo: URL to the logo of the provider.
    :info: Optional. Additional information for the provider.
      All keys are optional and omitted if that information is not available.

      :url: Website of the Provider (may be pCon.update specific)

    :filter_values: Contains various attributes providers can be filtered on.
      Contains a mapping of filter category to the values applicable for the provider

:filters: List of existing filters and their values. Each is an object with these properties

  :name: Language neutral name of the category.
  :text: Display name of this filter category.
  :values: List of objects representing the possible values of this filter category.

    :name: Language neutral name of this filter value. See `filter_values` key in providers list.
    :text: Display name of this value