2.0 API

(under construction)

The Spectral Workbench 2 API is very different from the v1 API. It is structured around a series of JavaScript classes:

Core classes

• SpectralWorkbench.js
• SpectralWorkbench.Graph.js - the graph, or chart, itself - the base class for the whole display
• SpectralWorkbench.Image.js - the image displayed above the graph
• SpectralWorkbench.Importer.js - a small class to manage import and parsing of server-side data requests into Sets and Spectra
• SpectralWorkbench.Datum.js - a superclass managing data from the server and tagging of such data
  • SpectralWorkbench.Set.js - set-data-specific class
  • SpectralWorkbench.Spectrum.js - similar to Set but for Spectra
• SpectralWorkbench.Tag.js - basic tagging class
  • SpectralWorkbench.PowerTag.js - more complex tagging including powertags and operations

API classes

• SpectralWorkbench.API.Core.js - commonly used/useful API methods
• SpectralWorkbench.API.Operations.js - operations that may be applied to spectra, in standardized format
• SpectralWorkbench.API.js
• SpectralWorkbench.API.Legacy.js - API methods and backwards-compatibility for 1.0 API

UI classes

• SpectralWorkbench.UI.TagForm.js
• SpectralWorkbench.UI.ToolPane.js - the class for the Pane interface itself
  • SpectralWorkbench.UI.SpectraPane.js - Panes which display a selection of spectra to use in manipulating the current Datum
  • SpectralWorkbench.UI.StepsPane.js - not yet used; Panes with sequential steps
• SpectralWorkbench.UI.ToolPaneTypes.js - the different types of ToolPanes
• SpectralWorkbench.UI.Util.js
• SpectralWorkbench.UI.Misc.js

There is also a REST API for accessing data in various formats programmatically.

---

Graph

A Graph is the basic display unit of Spectral Workbench, including at minimum a graph of some data, means to display, resize, refresh, and format the display, and perform unit conversions on that data. The Graph class is used in both spectrum and set display, and wraps a d3 line graph, using the NVD3 chart generator.

View commented code for more detail.

Datum

A Datum comes in two types, Spectrums and Sets. These share a number of methods, properties and behaviors.

View commented code for more detail.

Spectrum

View commented code for more detail.

Set

View commented code for more detail.

Image

As Spectral Workbench uses an image from your spectrometer, the Image class manages the display of the image alongside the Graph class, when viewing individual spectra. Much of this class relates to the resizing and display of the spectrum image for spectra with wavelength range limits, as the image is kept aligned with the graph data as much as possible.

View commented code for more detail.

Tag

Tagging is used to categorize and describe spectra, and to make them easier to search.

View commented code for more detail.

PowerTag

PowerTags, now known as Operations, are a type of tag used to manipulate spectral data in a reversible way. Operations are displayed to the right side of the screen in a separate area, and ordered by timestamp. Operations typically generate Snapshots of data, which are a flat copy of the spectrum's data after all Operations up to the current one have been run.

View commented code for more detail.

API

The API class has three main components, the Core API, Operations, and the Legacy API.

Core

Commonly used/useful API methods.

View commented code for more detail.

Operations

Code for individual operations that may be applied to spectra, in standardized format. As opposed to PowerTag, the class that defines common behaviors for all operations.

View commented code for more detail.

ToolPane

View commented code for more detail.

ToolPaneTypes

View commented code for more detail.

---

REST API

There are a variety of calls possible to access data programmatically with a REST API:

• Spectra are available using the buttons on each spectrum page (as shown below). They have standard URLs for:
  • JSON: https://spectralworkbench.org/spectrums/52027.json
  • CSV: https://spectralworkbench.org/spectrums/52027.csv
  • XML: https://spectralworkbench.org/spectrums/52027.xml
• Latest snapshot of a spectrum, at:
  • JSON: https://spectralworkbench.org/spectrums/latest/52027.json
  • CSV: https://spectralworkbench.org/spectrums/latest/52027.csv
  • XML: https://spectralworkbench.org/spectrums/latest/52027.xml
• Snapshots, via:
  • JSON: https://spectralworkbench.org/snapshots/2.json
  • CSV: https://spectralworkbench.org/snapshots/2.csv
  • XML: https://spectralworkbench.org/snapshots/2.xml
• Tags, via
  • JSON: https://spectralworkbench.org/tags/sky.json
  • XML: https://spectralworkbench.org/tags/sky.xml

Submitting spectra via POST request

It is possible for logged-in users to POST to: https://spectralworkbench.org/spectrums

with the following parameters:

• spectrum[title]
• tags (comma delimited)
• spectrum[notes]
• dataurl (a dataurl-encoded PNG of the data)
• geotag
• lat
• lon
• device (with values like "device:dsk" which actually just become tags)
• spectrum[calibration_id] (the id -- as in the URL -- of the spectrum to "clone" a calibration from)

This could enable periodic timed submission of data. However, we discourage users from abusing the API by submitting every minute or every second, which might force us to disable this form of submitting data. Please submit only 1 pixel tall images instead of whole images, and submit a maximum of once per hour.

An periodic sampling macro can be found here: https://gist.github.com/jywarren/4945996

---

1.0 API

The v1.0 Spectral Workbench API has been deprecated; its documentation has been archived here: https://publiclab.org/wiki/spectral-workbench-api-v1