.. _spv_for_dev:

==================
PVX for Developers
==================

For developers, it is possible to programmatically generate and
retrieve the result pages as HTML or PDF.


Getting data
============

To request a page, you will use the same URL that you would in a Web
browser. Filters are implemented in the URL in the form of GET
parameters:
``http://DOMAIN/PATH?filter.field1=value1&filter.field2=value2``

If the ``capture_begin`` or ``capture_end`` filters are omitted, the
engine will instead request data for the last hour.

The URL can be parameterized to ask the engine to render the output
either as stripped-down HTML, or as PDF. This is done by prepending,
respectively,
``/++skin++simplehtml/`` and ``/++skin++pdf/`` to the path part of the
URL:
``http://DOMAIN/++skin++pdf/PATH?filter.field1=value1&filter.field2=value2``

NB: This is the same kind of URL you get when you click the ‘Export
as PDF’ button in the user interface.


Authentication
==============

PVX normally uses its own authentication forms, which you see whenever
you log into the user interface with a Web browser. This
authentication system uses cookie-based sessions to keep you logged
in, which can be inconvenient to support programmatically.

PVX, therefore, provides support for session-less access with the Basic
HTTP Authentication mechanism. Command-line download clients like
``curl`` or ``wget`` support it natively.

There are two ways to switch PVX over to session-less Basic HTTP
Authentication:

1. Your download client may support it automatically. ``curl`` does.
   ``wget`` does if you pass the ``--auth-no-challenge`` command-line
   option. In this case, pass your login and password in the normal
   way supported by your client, and PVX will automatically
   authenticate your request using Basic HTTP Authentication.

2. Your download client may require the server itself to initiate the
   Basic HTTP Authentication process. For instance, ``wget`` does so
   when you omit the ``--auth-no-challenge`` option. If so, you can
   instruct PVX to initiate the process by appending
   ``&auth=force-http`` to the query string part of the URLs.

.. note::
  Basic HTTP Authentication does not protect your credentials from
  snooping. You may thus want to use ``https://`` URLs instead of
  ``http://``.


Scripting examples
==================

In the first example, we will retrieve the `Top Servers` page as a
stripped-down HTML, filtering for the `SSH` application using the
command-line with ``wget``:

.. code-block:: bash

  ## Using the --auth-no-challenge option:
  wget --user=admin --password=admin --auth-no-challenge 'http://PVX/++skin++simplehtml/nevrax/network/ipstats_dst.html?filter.capture_begin=2013-01-31+14:50&filter.capture_end=2013-01-31+15:50&filter.serviceid=ssh'

  ## Using the *auth* query string parameter:
  wget --user=admin --password=admin 'http://PVX/++skin++simplehtml/nevrax/network/ipstats_dst.html?filter.capture_begin=2013-01-31+14:50&filter.capture_end=2013-01-31+15:50&filter.serviceid=ssh&auth=force-http'

In the next example, we will retrieve the `Bandwidth Chart` page as a
PDF using the command-line with ``curl``:

.. code-block:: bash

  ## curl will automatically initiate Basic HTTP Authentication when you pass credentials with the '-u' option:
  curl -u admin:admin 'http://PVX/++skin++pdf/nevrax/network/bw_chart_page.html?filter.capture_begin=2013-01-31+14%3A51&filter.capture_end=2013-01-31+15%3A51&filter.serviceid=ssh' -o bandw_chart.pdf


If HTTPS is used to keep your credentials concealed, your client may
need an option to skip the server certificate check. Here is an
example with ``wget``:

.. code-block:: bash

  ## Same wget query as above, using HTTPS, and a terser way to pass credentials:
  wget --no-check-certificate 'https://admin:admin/PVX/++skin++simplehtml/nevrax/network/ipstats_dst.html?filter.capture_begin=2013-01-31+14:50&filter.capture_end=2013-01-31+15:50&filter.serviceid=ssh&auth=force-http'


Programming example
===================

You can also create a program to retrieve result pages from PVX. Here
is a simple example in `python2`:

.. code-block:: python

    import urllib
    import urllib2

    def get_spv_data(url, user, passw):

        ## create authentication
        auth = urllib2.HTTPPasswordMgrWithDefaultRealm()
        auth.add_password(None, url, user, passw)
        urllib2.install_opener(urllib2.build_opener(urllib2.HTTPBasicAuthHandler(auth)))

        ## request
        req = urllib2.Request(url)
        f = urllib2.urlopen(req)
        return f.read()


    def create_url(domain, page, filters={}, as_pdf=True):
        filter_args = {('filter.%s' % k): v for k, v in filters.iteritems()}
        filter_args = urllib.urlencode(filter_args)
        if as_pdf:
            skin = '++skin++pdf/'
        else:
            skin = '++skin++simplehtml/'
        return 'http://%s/%s%s?%s&auth=force-http' % (domain, skin, page, filter_args)


    ## set up the query
    domain = 'myspv-domain'
    page = 'nevrax/network/bw_chart_page.html'
    filters = {'capture_begin': '2013-01-31 14:50',
               'capture_end':   '2013-01-31 15:50',
               'serviceid':     'ssh',
               }
    user = 'admin'
    passw = 'admin'

    url = create_url(domain, page, filters, as_pdf=True)
    result = get_spv_data(url, user, passw)
    open("output.pdf", "w").write(result)