.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)       : ******************** with overline
  Sections (H3)       : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)     : """""""""""""""""""""

.. meta::
 :description: Using the WAPT server APIs
 :keywords: API, Application Protocol Interface, WAPT, documentation

.. _using__wapt_api:

##########################
Using the WAPT Server APIs
##########################

.. note::

  This documentation does not describe all the available :abbr:`APIs (Application Protocol Interfaces)`, it will however concentrate on the most useful ones.

All available API URLs may be found in :file:`/opt/wapt/waptserver/server.py`.

URLs are formed by calling the proper command from the WAPT Server, ex: :file:`https://srvwapt/{command_path}`.

.. hint::

  This documentation contains examples using Python code or curl.

.. warning::

  Since version 2.5, most API URLs are protected with SSL client certificates. You will have to modify your scripts (cf. examples below).

******
API V1
******

/api/v1/hosts
=============

* Get registration data of one or several hosts.

  .. code-block:: python

    # Args:
    #     has_errors (0/1): filter out hosts with packages errors
    #     need_upgrade (0/1): filter out hosts with outdated packages
    #     groups (csvlist of packages): hosts with packages
    #     columns (csvlist of columns):
    #     uuid (csvlist of uuid): <uuid1[,uuid2,...]>): filter based on uuid
    #     filter (csvlist of field):regular expression: filter based on attributes
    #     not_filter (0,1):
    #     limit (int): 1000
    #     trusted_certs_sha256 (csvlist): filter out hosts based on their trusted package certs

    # Returns:
    #     result (dict): {'records':[],'files':[]}
    #     query:
    #       uuid=<uuid>
    #     or
    #       filter=<csvlist of fields>:regular expression
    # """

* List all hosts using the following parameters:

  * *reachable*;

  * *computer_fqdn* ==> computer_name;

  * *connected_ips*;

  * *mac_addresses*.

  This example shows a request with parameters:

  .. code-block:: python

    cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
    advanced_hosts_wapt = wgets('https://%s:%s@%s/api/v1/hosts?columns=reachable,computer_fqdn,connected_ips,mac_addresses&limit=10000' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
    parsed = json.loads(advanced_hosts_wapt)
    print(json.dumps(parsed, indent=1, sort_keys=True))

  This example is a global request:

  .. code-block:: python

    cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
    hosts_wapt = wgets('https://%s:%s@%s/api/v1/hosts' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
    parsed = json.loads(hosts_wapt)
    print(json.dumps(parsed, indent=1, sort_keys=True))

  .. hint::

    This is the same exemple with a simple html request:

    .. code-block:: batch

      https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/hosts

    This one just show request with reachable status, the computer name, its connected ips and its mac addresses.
    The display limit is 10000.

     .. code-block:: batch

        https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/hosts?columns=reachable,computer_fqdn,connected_ips,mac_addresses&limit=10000

/api/v1/groups
==============

* Get all group packages. Group is found with section *group* in the package:

  .. code-block:: python

    cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
    group_wapt = wgets('https://%s:%s@%s/api/v1/groups' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
    parsed = json.loads(group_wapt)
    print(json.dumps(parsed, indent=1, sort_keys=True))

  .. hint::

    This is the same exemple with a simple html request:

    .. code-block:: batch

      https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/groups

/api/v1/host_data
=================

dmi
---

* Get :abbr:`DMI (Desktop Management Interface)` info for a host:

.. note::

    #
    #    Get additional data for a host
    #    query:
    #      uuid=<uuid>
    #      field=packages, dmi or softwares

.. note::

  *dmi* is not the only available option.
  You can also lookup information using *installed_packages*, *wsusupdates* ou *installed_softwares*.

.. code-block:: python

    cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
    dmi_host_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=dmi' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
    #print(dmi_host_data_wapt)
    parsed = json.loads(dmi_host_data_wapt)
    print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=dmi

installed_packages
------------------

Option *installed_packages* will list all packages installed on a specific host.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  install_packages_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=installed_packages' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(install_packages_data_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=installed_packages

installed_softwares
-------------------

Option *installed_softwares* will list all softwares installed on a specific host.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  install_softwares_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=installed_softwares' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  #print(install_softwares_data_wapt)
  parsed = json.loads(install_softwares_data_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

   This is the same exemple with a simple html request:

   .. code-block:: batch

      https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=installed_softwares

wsusupdates
-----------

Option *wsusupdates* will list all Windows Updates installed on a specific host.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  wsusupdates_data_wapt = wgets('https://%s:%s@%s/api/v1/host_data?uuid=UUID&field=wsusupdates' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  #print(wsusupdates_data_wapt)
  parsed = json.loads(wsusupdates_data_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/host_data?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD&field=wsusupdates

/api/v1/usage_statistics
========================

Get usage statistics from the WAPT Server.

.. hint::

  This API is useful if you have several WAPT Servers and you want to know how many hosts are there.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  usage_statistics_wapt =wgets('https://%s:%s@%s/api/v1/usage_statistics' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  #print(usage_statistics_wapt)
  parsed = json.loads(usage_statistics_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v1/usage_statistics

******
API V2
******

/api/v2/waptagent_version
=========================

Display :program:`waptagent.exe` version.

.. code-block:: python

  waptagent_version = wgets('https://%s:%s@%s/api/v2/waptagent_version' % (wapt_user,wapt_password,wapt_url))
  parsed = json.loads(waptagent_version)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

   This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v2/waptagent_version

******
API V3
******

/api/v3/packages
================

List packages on the repository, retrieve the :file:`control` files of WAPT packages.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  packages_wapt = wgets('https://%s:%s@%s/api/v3/packages' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(packages_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/packages

/api/v3/known_packages
======================

List all packages with last *signed_on* information.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  known_packages_wapt = wgets('https://%s:%s@%s/api/v3/known_packages' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(known_packages_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/known_packages

/api/v3/trigger_cancel_task
===========================

Cancel a running task.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  trigger_cancel_task = wgets('https://%s:%s@%s/api/v3/trigger_cancel_task' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(trigger_cancel_task)
  print(json.dumps(parsed, indent=1, sort_keys=True))

/api/v3/get_ad_ou
=================

List :abbr:`OU (Organizational Unit)` seen by hosts and displayed in the WAPT Console.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  get_ad_ou = wgets('https://%s:%s@%s/api/v3/get_ad_ou' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(get_ad_ou)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/get_ad_ou

/api/v3/get_ad_sites
====================

List Active Directory sites.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  get_ad_sites = wgets('https://%s:%s@%s/api/v3/get_ad_sites' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(get_ad_sites)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/get_ad_sites

/api/v3/hosts_for_package
=========================

List hosts with a specific package installed.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  hosts_for_package = wgets('https://%s:%s@%s/api/v3/hosts_for_package?package=PACKAGE' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(hosts_for_package)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/hosts_for_package?package=demo-namepackage

/api/v3/host_tasks_status
=========================

List tasks on a particular host.

.. code-block:: python

  cert_path = (r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt',r'C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem')
  host_tasks_status = wgets('https://%s:%s@%s/api/v3/host_tasks_status?uuid=UUID' % (wapt_user,wapt_password,wapt_url),verify_cert=False,cert=cert_path)
  parsed = json.loads(host_tasks_status)
  print(json.dumps(parsed, indent=1, sort_keys=True))

.. hint::

  This is the same exemple with a simple html request:

  .. code-block:: batch

    https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/host_tasks_status?uuid=14F620FF-DE70-9E5B-996A-B597E8F9B4AD

.. attention::

   **Next API are with POST method**.

/api/v3/upload_packages
=======================

.. todo::

   Tests

/api/v3/upload_hosts
====================

.. todo::

   Tests

/api/v3/change_password
=======================

Change the Admininistrator password [only this account].
The request is a python dictionnary *{}* with keys:

* *user*;

* *old_password*;

* *new_password*.

.. code-block:: bash

  curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"user":"USER","password":"old_password","new_password":"new_password"}' -H "Content-Type: application/json" "https://user:old_password@srvwapt/api/v3/change_password"

/api/v3/login
=============

Initialize a connection to the WAPT Server.

.. code-block:: bash

  curl --insecure -X POST --data-raw '{"user":"admin","password":"MYPASSWORD"}' -H "Content-Type: application/json" "https://srvwapt.mydomain.lan/api/v3/login"

  {"msg": "Authentication OK", "result": {"edition": "enterprise", "hosts_count": 6, "version": "1.7.4", "server_domain": "mydomain.lan", "server_uuid": "32464dd6-c261-11e8-87be-cee799b43a00"}, "success": true, "request_time": 0.03377699851989746}

.. hint::

   We can make a connection by html form then POST:
   https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/get_ad_sites

/api/v3/packages_delete
=======================

Delete package with a precise version.
The request is a python list *[]*.
A list of packages may be given, separated by commas *,*.

Example:

.. code-block:: bash

  curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '["demo-libreoffice-stable_5.4.6.2-3_all.wapt"]' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/packages_delete"

/api/v3/reset_hosts_sid
=======================

Reinitialize all host connections.

For the POST method, the syntax is: :code:`--data-raw` a dictionnary list with :code:`uuids` as keys and the UUIDs of the hosts as values.

.. code-block:: bash

   curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/reset_hosts_sid"

   {"msg": "Hosts connection reset launched for 1 host(s)", "result": {}, "success": true, "request_time": null}

.. hint::

  If you want several hosts:

  .. code-block:: bash

    curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID#1","UUID#2"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/reset_hosts_sid"

    {"msg": "Hosts connection reset launched for 2 host(s)", "result": {}, "success": true, "request_time": null}

/api/v3/trigger_wakeonlan
=========================

If hosts are WakeOnLan enabled, this API is useful.

Syntax is :file:`--data-raw`: a dictionnary with key *uuids* and a list of host uuids.

.. code-block:: bash

  curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/trigger_wakeonlan"

  {"msg": "Wakeonlan packets sent to 1 machines.", "result": [{"computer_fqdn": "computer_fqdn", "mac_addresses": ["mac_addresses"], "uuid": "UUID"}], "success": true, "request_time": null}

.. hint::

  If you want several hosts:

  .. code-block:: bash

    curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID#1","UUID#2"]}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/trigger_wakeonlan"

    {"msg": "Wakeonlan packets sent to 2 machines.", "result": [{"computer_fqdn": "computer_fqdn#1", "mac_addresses": ["mac_addresses#1"], "uuid": "UUID#1"}, {"computer_fqdn": "computer_fqdn#2", "mac_addresses": ["mac_addresses#2"], "uuid": "UUID#2"}], "success": true, "request_time": null}

/api/v3/hosts_delete
====================

.. code-block:: python

    """Remove one or several hosts from the WAPT Server database and optionnally the host packages

    Args:
        uuids (list): list of uuids to delete
        filter (csvlist of field:regular expression): filter based on attributes
        delete_packages (bool): delete host's packages
        delete_inventory (bool): delete host's inventory

    Returns:
        result (dict):
    """

If you want to delete a host from the inventory:

.. code-block:: bash

  curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"],"delete_inventory":"True","delete_packages":"True"}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/hosts_delete"

  {"msg": "1 files removed from host repository\n1 hosts removed from DB", "result": {"files": ["/var/www/wapt-host/UUID.wapt"], "records": [{"computer_fqdn": "computer_fqdn", "uuid": "UUID"}]}, "success": true, "request_time": null}

If you do not want to delete from the inventory:

.. code-block:: bash

   curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST --data-raw '{"uuids":["UUID"],"delete_inventory":"False","delete_packages":"False"}' -H "Content-Type: application/json" "https://admin:MYPASSWORD@srvwapt.mydomain.lan/api/v3/hosts_delete"

   {"msg": "0 files removed from host repository\n1 hosts removed from DB", "result": {"files": [], "records": [{"computer_fqdn": "computer_fqdn", "uuid": "UUID"}]}, "success": true, "request_time": null}

/api/v3/trigger_host_action
===========================

.. todo::

  Tests

/api/v3/upload_waptsetup
========================

.. code-block:: python

   # Upload waptsetup

   #Handle the upload of customized waptagent.exe into wapt repository

   ### DOES NOT WORK
   #curl --cert "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.crt" --key "C:\Program Files (x86)\wapt\private\71253c6c-f412-455b-a907-93b10ce07490.pem" --insecure -X POST -H "Content-Type: multipart/form-data" -F 'data=@waptagent.exe' "https://admin:MYPASSWORD@srvwapt.mydomain.lan/upload_waptsetup"

/api/v3/ping
============

Ping shows a general set of informations on a WAPT Server.

.. code-block:: python

  # https://srvwapt.mydomain.lan/ping
  # Lists WAPT Server informations

  ping_wapt = wgets('https://%s:%s@%s/ping' % (wapt_user,wapt_password,wapt_url))
  parsed = json.loads(ping_wapt)
  print(json.dumps(parsed, indent=1, sort_keys=True))