.. _section-hawat-plugin-networks:

networks
================================================================================

.. automodule:: hawat.blueprints.networks
    :noindex:

.. _section-hawat-plugin-networks-endpoints:

Provided endpoints
--------------------------------------------------------------------------------

``/api/networks/get``
    * *Reference:* :ref:`section-hawat-plugin-networks-webapi-get`


.. _section-hawat-plugin-networks-webapi:

Web API
--------------------------------------------------------------------------------

For general information about web API please refer to section :ref:`section-hawat-webapi`.

Following is a list of all currently available API endpoints. These endpoints
provide results as JSON document instead of full HTML page.


.. _section-hawat-plugin-networks-webapi-get:

API endpoint: **get**
````````````````````````````````````````````````````````````````````````````````

**Relevant endpoint:**

``/api/networks/get``
    * *Authentication:* login required
    * *Authorization:* maintainer, admin
    * *Methods:* ``GET``


**Response format**

JSON document, that will be received as a response for the search, contains the
following keys:

``data``
    * *Description:* This key contains a list of networks. Every network is a dictionary with following keys:

      * ``client_id`` - The value of ``client_id`` of the network stored in the database
      * ``descr`` - Description of the network
      * ``netname`` - Name of the network
      * ``rank`` - Rank of the network, used for reporting
      * ``source`` - The source of the network
      * ``resolved_abuses`` - A dictionary which may contain the following keys:

        * ``low`` - A list of email addresses used for reporting events with low severity
        * ``medium`` - A list of email addresses used for reporting events with medium severity
        * ``high`` - A list of email addresses used for reporting events with high severity
        * ``critical`` - A list of email addresses used for reporting events with critical severity
        * ``fallback`` - A list of fallback email addresses
      * the IP address of the network, which could be either

        * ``IP4_start`` and ``IP4_end``, or
        * ``IP6_addr`` and ``IP6_prefix``
    * *Datatype:* ``list of dictionaries``

``view_icon``
    * *Description:* This subkey is always present in the response. It is intended
      for internal purposes.
    * *Datatype:* ``string``

``view_title``
    * *Description:* This subkey is always present in the response. It is intended
      for internal purposes.
    * *Datatype:* ``string``

**Example response:**

.. code-block:: json

    {
      "data": [
        {
          "client_id": 123456,
          "descr": "First demonstration IPv4 network",
          "ip4_end": "192.168.0.255",
          "ip4_start": "192.168.0.0",
          "netname": "NETNAME1",
          "rank": 999,
          "resolved_abuses": {
            "low": [
              "abuse@bogus-domain.org"
            ]
          },
          "source": "manual"
        },
        ...
      ],
      "view_icon": "module-networks",
      "view_title": "Networks"
    }

**Example usage with curl:**

.. code-block:: shell

    $ curl -X GET -d "api_key=your%AP1_k3y" "https://.../api/networks/get"