11.1.2 RESTful API

This section details the endpoints supported by the plot servlet; it is not required reading for those who want to use the supplied plot2Lib.js JavaScript library, but may be of interest to those who want to write their own JavaScript clients.

General URL Syntax

The plot service accepts URLs of the form

   <base-url>/<action-type>/<plot-spec>[?<session-id>&<arg-list>]

These parts are expanded as follows:

<action-type>

The action type string determines the kind of request, and is one of the strings "html", "state", "imgsrc", "position", "count", "row"; see below for details.

<plot-spec>

The plot specification is an ampersand-separated STILTS plot command string; the form is "<command-name>&<arg-name>=<value>&<arg-name>=<value>..." for instance "plot2sky&layer1=mark&in1=stars.vot&lon1=ra&lat1=dec". See STILTS plotting documentation in Section 8 for command syntax. Note that although this part contains &-separated name=value pairs which are syntactically application/x-www-form-urlencoded it is part of the URI path and not a URI query string since it does not come after a question mark ('?') and it cannot be supplied by POSTing parameters.

<session-id>

The session identifier is of the form "sessionId=<unique-string>" and it serves to maintain the state of the plot between requests (so that for instance a navigation action starts from where the last one left off). The <unique-string> string is chosen by the client; any string value is permitted, but it's up to the client to pick something that is unlikely to be chosen by other unrelated clients on the same or different machines. Incorporating a high-resolution timestamp is a good bet. In case of a collision, confusing results may ensue, but it's probably not necessary to resort to cryptographic-grade hashing. This part is not necessary for the "html" <action-type>.

<arg-list>

A list of zero or more ampersand-separated "<name>=<value>" parameters, specific to the <action-type>; see below for details.

The [?<session-id>&<arg-list>] part of the URL is an application/x-www-form-urlencoded query-string, and may be supplied as a POST body rather than as part of the GET query if preferred. Note that does not apply to the <plot-spec> part, which is in RFC3986 terms part of the path and not part of the query.

Available Action Types

The options for the various different values of the <action-type> string, with their associated parameters and response values, are as follows:

html

Returns a new standalone HTML page containing the interactive plot specified by the supplied plot specification. Note this does not require a session ID to be supplied, and it has no parameters. This action is easy to use, but not very flexible.

state

Returns a JSON structure giving the image and/or image annotations for the current state of the session. The session state may be updated by supplying navigation parameters, as follows:

• navigate=reset: reset the plot to initial state
• navigate=resize&size=width,height: resize the plot to width x height pixels
• navigate=click&pos=x,y&ibutton=1|2|3: emulate TOPCAT click on plot at graphics position x,y
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3: emulate TOPCAT continuing drag from start graphics position x0,y0 to x1,y1
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3&end=true: emulate TOPCAT end-drag from start graphics position x0,y0 to x1,y1
• navigate=wheel&pos=x,y&wheelrot=nstep: emulate TOPCAT mouse wheel at graphics position x,y
• navigate=none: no change to last position

The members of the returned structure are:

imgSrc (present if plot has changed since last request):

Contains a data: URL suitable for use as the content of an IMG/@src attribute to display the current state of the plot

staticSvg (present if there are static decorations):

SVG content, suitable as the content of an SVG node, giving decorations to superimpose over the plot image.

transientSvg (present if there are transient decorations):

SVG content, suitable as the content of an SVG node, giving decorations to superimpose over the plot image representing a navigation action. Such decorations should only be displayed for a short time (e.g. 0.5 second).

bounds (present for planar and cubic plots):

A 2- or 3-element array of (lower,upper) data bound pairs giving the extent of the current plot.

imgsrc

Returns image data suitable for reference by an IMG/@src attribute value for the current state of the session. The session state may be updated by supplying navigation parameters as follows:

• navigate=reset: reset the plot to initial state
• navigate=resize&size=width,height: resize the plot to width x height pixels
• navigate=click&pos=x,y&ibutton=1|2|3: emulate TOPCAT click on plot at graphics position x,y
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3: emulate TOPCAT continuing drag from start graphics position x0,y0 to x1,y1
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3&end=true: emulate TOPCAT end-drag from start graphics position x0,y0 to x1,y1
• navigate=wheel&pos=x,y&wheelrot=nstep: emulate TOPCAT mouse wheel at graphics position x,y
• navigate=none: no change to last position

The response MIME type can be influenced by the ofmt parameter in the <plot-spec> or the format parameter in the <arg-list>. In case of disagreement, the latter takes precedence. The available options are "png", "png-transp", "gif", "jpeg", "pdf", "svg", "eps", "eps-gzip".

position

Provides a service to convert a position in plot graphics coordinates to data coordinates. The request must have a pos argument giving the graphics position in the form x,y (e.g. "pos=203,144"), and the response will be a JSON structure with the following members:

dataPos:

On success, contains data coordinates as a numeric array.

txtPos:

On success, contains data coordinates as a formatted string.

message:

Textual indication of conversion status. It will be "ok" on success, but may have some other value, such as "out of plot bounds", on failure.

count

Returns the number of points currently visible in this plot. Note that determining this value does take some computation (it's not free). The output is a plain text decimal value; it can also be interpreted as JSON.

row

Services a request for row information, at or near a submitted graphics position on the plot. The request must have a pos argument giving the graphics position in the form x,y (e.g. "pos=203,144"),

The output is a JSON array of objects; there is one array element for each table represented, and each such element is a column-name->column-value map for the row indicated. If the submitted point is not near any plotted points, the result will therefore be an empty array.

This API is subject to extension or modification in future releases.