===========
Use the API
===========

--------
Overview
--------

All components that are using the full architecture of OPNsense
automatically receive API capabilities, for this simple tutorial we use
the firmware module but others will function in the same way. API access
is part of the local user authentication system, but uses key/secret
pairs to separate account information from machine to machine
communication. Secrets are not stored on OPNsense and can be downloaded
only once, if lost, a new key has to be generated for your application.

A user can have multiple keys, our advice is to create a unique key for
every application in use.

-------------
Creating keys
-------------

API keys are managed in the user manager (system\_usermanager.php), go
to the user manager page and select a user. Somewhere down the page you
will find the api section for this user.

|Usermanager add api key.png|

Click on the + sign to add a new key. When the key is created, you will
receive a (single download) with the credentials in one text file (ini
formatted). The contents of this file look like this:

.. code-block:: c

    key=w86XNZob/8Oq8aC5r0kbNarNtdpoQU781fyoeaOBQsBwkXUt
    secret=XeD26XVrJ5ilAc/EmglCRC+0j2e57tRsjHwFepOseySWLM53pJASeTA3

--------------------
Code sample (python)
--------------------

For the python code sample we use the nice "requests" library
(http://docs.python-requests.org/en/latest/), which makes http calls
very easy.

Before you can start, make sure your OPNsense has a valid SSL
certificate (or choose to ignore it for testing purposes by setting
verify=False), don't forget to verify that the selected user may access
the firmware page.

The web interface uses the same logic that will be available for the
api, in this example we will collect some status information from the
firmware module and print it out for the user.

It all starts with creating the request and waiting for the response,
all data interaction is using json format, both for the responses as for
the request data (when sending POST data).

First step of the example is importing the required libraries, then
define the endpoint url and credentials to use and finally fire the (get
type) request. As soon as we receive the response, we parse the json
string back to a dictionary and print some data depending on the
response.

.. code-block:: php

   # import libraries
   import json
   import requests

   # define endpoint and credentials
   api_key = 'w86XNZob/8Oq8aC5hxh2he+vLN00r0kbNarNtdpoQU781fyoeaOBQsBwkXUt'
   api_secret = 'puOyw0Ega3xZXeD26XVrJ5WYFepOseySWLM53pJASeTA3'
   url = 'https://192.168.1.1/api/core/firmware/status'
 
   # request data
   r = requests.get(url,
                    verify='OPNsense.pem',
                    auth=(api_key, api_secret))

   if r.status_code == 200:
       response = json.loads(r.text)

       if response['status'] == 'ok' and response['status_upgrade_action'] == 'all':
           print ('OPNsense can be upgraded')
           print ('download size : %s' % response['download_size'])
           print ('number of packages : %s' % response['updates'])
           if response['upgrade_needs_reboot'] == '1':
               print ('REBOOT REQUIRED')
       elif response['status'] == 'ok' and response['status_upgrade_action'] == 'pkg':
           print ('OPNsense can be upgraded, but needs a pkg upgrade first')
       elif 'status_msg' in response:
           print (response['status_msg'])
   else:
       print ('Connection / Authentication issue, response received:')
       print r.text


----------
Using curl
----------

Simple testing with curl is also possible, the sample below uses the
same credentials, but ignores the ssl certificate check (-k) for
testing.

.. code-block:: sh

    curl -k -u "w86XNZob/8Oq8aC5hxh2he+vLN00r0kbNarNtdpoQU781fyoeaOBQsBwkXUt":"puOyw0Ega3xZXeD26XVrJ5WYFepOseySWLM53pJASeTA3" https://192.168.1.1/api/core/firmware/status


And schedule the actual upgrade of all packages using:

.. code-block:: sh

    curl -XPOST -d '{"upgrade":"all"}' -H "Content-Type: application/json" -k -u "w86XNZob/8Oq8aC5hxh2he+vLN00r0kbNarNtdpoQU781fyoeaOBQsBwkXUt":"puOyw0Ega3xZXeD26XVrJ5WYFepOseySWLM53pJASeTA3" https://10.211.55.100/api/core/firmware/upgrade


.. |Usermanager add api key.png| image:: images/Usermanager_add_api_key.png
   :width: 700px