Snapple/Perl API

Table of Contents

• Overview
• Using the Snapple Tool
• Using the Snapple API

Overview

Snapple is a Perl tool that allows you to access Snap2 from the command line. It presents a command line interface that more or less reflects the set of operations you can perform from the web interface, albeit in a more Unix-y way. It has a few additional mechanisms that make sense for a command line tool, but not for a web interface, such as the ability to create aliases, or use multiple connections, or to run in batch mode to execute a series of Snapple commands unattended.

Snapple works by using the Perl package LWP::UserAgent to send GET (and sometimes POST) requests to a Snap2 instance on one of our servers. The default is https://newdev.shodor.org/snap2, but you can change this. There is a PHP controller in Snap2 to which all these requests are sent and this script executes them, produces some sort of result data and sends that back using JSON, which snapple interprets and uses to report information back to the user. Because of this interfaces, you can use snapple anywhere you have access to Snap2 via a web browser. You will need to have certain Perl packages installed, though (as well as Perl itself, of course), so you cannot simply take the snapple script and the Snap2 directory and run snapple on any machine. Right now, it is only guaranteed to run on login.shodor.org, where all the packages are installed.

There is also a Perl API for Snap2, which snapple uses to implement most of its base functionality. This API can be used independently of the command line interface. You need only use the Snap2API module and then call snapAPIInit(). The API is object-oriented, but that API is built on top of a procedural API, which supports all of the functionality currently supported by snapple in any form. As such, you may occasionally have to use the procedural API (or fix the OO API to support the missing functionality :).

Using the Snapple Tool

This section goes over using the snapple command line tool.

Using the Snapple API

As mentioned above in the Overview section, the Snapple API is two-fold: with a "nice" object-oriented API, and a lower-level procedural API, upon which the OO API is built. Let's start with the OO API and work our way down. The ultimate documentation will, of course, be the source code. As such, part of this guide will be dedicated to explaining the organization of the API internals so that you can find out how things work yourself.

Object-Oriented API

The object-oriented API consists of a set of classes that represent, more or less, the Snap2 objects on the server. The following four main objects are supported:

• Snap2File: base class for directories and resources (=SnapFile)
• Snap2Directory: a Snap2 directory (= SnapDirectory)
• Snap2Resource: a Snap2 resource (= SnapResource)
• Snap2Version: a Snap2 version (= SnapVersion)

Some of the methods are even the same, such as submit(), which is equivalent to SnapVersion::submit(). Note that all method names in Perl are lowercase with underscores separating words. This is only true for methods. Functions that do not belong to objects are camelCased and are almost always prefixed with "snap", e.g., snapInit().

To use the API, you must use the Snap2API module in your Perl script and the Snap2/ directory from common/snap2/perl must be in the same directory as (or in the library path of) your script. You must then call snapAPIInit(). And that's all that is required for set up! The following example illustrates that and also shows some usage of the API, which be explained below:

#! /usr/bin/perl

use Snap2::API;

snapAPIInit();

my $v = new Snap2::Version '//test/mediatest@1';
print "Ordinal: $v->ordinal\n";

This code creates a new version object based on the Snap2 path given and then displays the ordinal of that version, which will be '1'.