webservices_soap.md

Web Services and SOAP API

The Sightline web services and SOAP API work in much the same way. Each service inherits from an abstract class so most of the methods are the same for each. You can easily swap between the SOAP API and Web Services API.

The difference is that you should use the SOAP API when querying for data with filters containing multiple values (such as traffic data filtered by multiple interfaces). The web services API encodes the XML into a GET request which can exceed the maximum URI length (Error 414) when using multiple filter values.

Traffic Graphs

Traffic graph functions get a PNG image generated by Sightline based on a query and a graph definition both in XML. Searching for Query XML or Graph XML in the online documentation for Sightline or through the API guides gives some insight into how the XML should look.

There are also some helper functions to build the XML along with some wrapper functions for getting common graphs.

Filters

Filters can be defined in the Query XML functions to build the filter matches (as per the Sightline documentation). Filters are an array with the type (aspath, peer, customer, interface etc) and the query value applied to the filter. If binby is true it displays each unique data stream on the graph as separate lines with a legend. Value can be a single scalar value or an array of values.

// Aspath filter to search for traffic date from aspath regexp '_701_'. Will show each AS Path found
// as individual graph items.

$filters = [
    ['type' => 'aspath', 'value' => '_701_', 'binby' => true],
];

// Filter by peer managed object with ID of 10. Show traffic graphs with individual graph items on a per
// application basis.

$filters = [
    ['type' => 'peer', 'value' => '10', 'binby' => false],
    ['type' => 'application', 'value' => null, 'binby' => true]
];

// Filter by multiple interface IDs and then broken down by AS PATH. Use interfaces
// for the graph items.

$interfaceIds = ['1234', '24424', '56778', '991122', '333344'];

$filters = [
    ['type' => 'interface', 'value' => $interfaceIds, 'binby' => true],
    ['type' => 'aspath', 'value' => '_'.$ASnum.'_', 'binby' => false],
];

Filters are limited to two filters per query by Sightline. There are however no checks for this in the class. Look at the API class for more examples of filters in each of the helper functions.

Peer Managed object Traffic graph

The following adds gets a traffic graph from an Sightline deployment for a peer based on the peer Managed Object. It base64 encodes the image for use inline in the template.

// src/Controller/PeerController.php

use Robwdwd\SightlineApiBundle\SightlineWebServices;

public function show(Peer $peer, SightlineWebServices $sightlineWS, $page): Response
{

    $trafficGraph = base64_encode($sightlineWS->getPeerTrafficGraph(
        $peer->getSightlineMoId(),
        htmlspecialchars($peer->getName().' - AS'.$peer->getAsn())
    ));

    return $this->render('peer/show.html.twig', [
        'peer' => $peer,
        'trafficGraph' => $trafficGraph
    ]);
 }

In your twig template you can use the following to display the image in the browser.

<img src="data:image/png;base64,{{trafficGraph|raw}}">

AS Path Graph

This builds a traffic graph based on an AS Path filter. There is a helper function to do this but this example shows how to use the buildQueryXML and buildGraphXML functions.

// src/Controller/PeerRequestController.php

use Robwdwd\SightlineApiBundle\SightlineWebServices;

public function show(PeeringRequest $peeringRequest, SightlineWebServices $sightlineWS, $page): Response
{

    // Build a filter line for the Query XML.
    $filters = [
        ['type' => 'aspath', 'value' => '_'.$peeringRequest->getAsn().'_', 'binby' => true],
    ];

    // Query for date from the past four weeks (21 days ago until now) and display in bps.
    //
    $queryXML = buildQueryXML($filters, '21 days ago', 'now', 'bps')

    // Build the graph XML with title 'ASN traffic'. By default units are bps but should match the data query.
    $graphXML = $this->buildGraphXML('ASN traffic');

    $$trafficGraph = base64_encode($sightlineApi->getTrafficGraph($queryXML, $graphXML));

    return $this->render('peeringRequest/show.html.twig', [
        'peeringRequest' => $peeringRequest,
        'trafficGraph' => $trafficGraph
    ]);
}

Detail graph for a peer managed object

This example builds a detail style graph for a peer managed object containing data from the last week. It displays a graph item for in, out and total traffic. binby should be false for detail style traffic graphs. You can also use the getPeerTrafficGraph() method which does the same thing.

// src/Controller/PeerController.php

use Robwdwd\SightlineApiBundle\SightlineWebServices;

public function show(Peer $peer, SightlineWebServices $sightlineWS, $page): Response
{
    $filters = [
        ['type' => 'peer', 'value' => $peer->getSightlineMoID, 'binby' => false],
    ];

    // The last argument to the QueryXML build is for each class of traffic that should be
    // retried (and displayed). The array can contain: in, out, total, backbone and dropped.
    // See Sightline documentation for up-to-date class fields.
    //
    $queryXML = $this->buildQueryXML($filters, '7 days ago', 'now', 'bps', ['in', 'out', 'total']);

    // Build the graph, this time set the last argument 'detail' to true to get a detailed graph.
    // Also set width to 800 and height to 150.
    //
    $graphXML = $this->buildGraphXML('Peer traffic', 'bps', true, 800, 150);

    $trafficGraph = base64_encode($sightlineApi->getTrafficGraph($queryXML, $graphXML));

    return $this->render('peer/show.html.twig', [
        'peer' => $peer,
        'trafficGraph' => $trafficGraph
    ]);
}