JSONREST

JSONREST is a client library for discoverable REST APIs using JSON payloads.

>>> import jsonrest
>>> j = jsonrest.JSONREST('http://example/')
>>> dir(j)
['foo', 'bar', 'baz']
>>> j.foo
JSONREST('http://example/foo/', ['x', 'y', 'z'])
>>> j.foo.x = 42
>>> print(j.foo.x)
42

JSONREST exposes the REST API as an object-oriented interface, with the object hierarchy mirroring the directory structure of the URLs. In order to make this work, it depends on the server responding to GET requests on directories with a JSON array containing all available API endpoints (or other directories) that reside there, with directories identified by a trailing forward-slash (/).

Installing

JSONREST is available on PyPI:

$ python -m pip install vti-jsonrest

Documentation

Full documentation is available at jsonrest.readthedocs.io.

Supported Versions

JSONREST officially supports Python 2.7 & 3.6+.

Features

  • Makes REST APIs behave like a normal python object

  • Supports tab-completion in REPLs and Jupyter notebooks

  • Keep-Alive & Connection Pooling

Members

class jsonrest.JSONREST(base, members=None, session=None)

Bases: object

A class providing access to discoverable REST APIs using JSON payloads. The REST server must respond to GET requests on directories with an array containing the names of the available properties and subdirectories within it.

The directory names in the URIs are converted into a nested tree of JSONREST objects, in which each endpoint URI is available as a class instance attribute. All payloads use JSON, and Python data types are automatically converted back and forth from JSON.

To do a PUT of the value 42 to the URI http://example/foo/bar, then perform a GET on the same URI and print the result, do the following:

rest = JSONREST('http://example/')
rest.foo.bar = 42
print(rest.foo.bar)

In interactive interpreters such as ipython or jupyter notebooks, the available URIs are discoverable via tab-completion.

Parameters:

  • base – The top-level base URI at which the API is hosted.

  • members – The names of subdirectories and properties available at the base URI. This will be queried from the API if not specified.

  • session – The requests session to perform all HTTP operations with. Reusing the same session for all connections to the same host minimizes overhead.

_child(name, members)

Construct a new JSONREST object representing a subdirectory of this one.

Parameters:

  • name – The name of the subdirectory.

  • members – The names of items within the subdirectory.

get(uri)

Perform a GET.

Parameters:

uri – The URI to perform the GET on, relative to the base path of this object.

:return The message body of the response, converted from json to native python data types.

put(uri, data)

Perform a PUT.

Parameters:

  • uri – The URI to perform the PUT on, relative to the base path of this object.

  • data – The data to send; it will be converted to JSON then included as the message body.

exception jsonrest.VTIInstrumentError(arg)

Bases: Exception

A base class representing the types of errors raised by VTI Instruments REST APIs.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception jsonrest.VTIInstrumentErrorArgs(args, error_code, resource)

Bases: VTIInstrumentError

An error object returned from a VTI Instruments REST API, with arguments that can be used to fill in an error message template.

In order to construct the full error message, find the message associated with error_code, and replace each “%s” in it with the next member of args.

Variables:

  • args – The arguments for filling in the error message template

  • error_code – The numerical error code

  • resource – The URI that the error was raised by

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception jsonrest.VTIInstrumentErrorMessage(message, error_code, resource)

Bases: VTIInstrumentError

An error object returned from a VTI Instruments REST API, with a fully populated error message.

Variables:

  • message – The error message.

  • error_code – The numerical error code

  • resource – The URI that the error was raised by

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class jsonrest.VTIREST(host, slot='inst0', path='', members=None, session=None)

Bases: JSONREST

Wraps the JSONREST class to provide easier access to the JSON-REST APIs of VTI Instruments products.

Constructs the proper base URI for a certain slot name automatically, and properly handles the HTTP 240 status code that VTI Instruments products use to indicate an error, querying the error queue and raising a VTIInstrumentError exception using the result.

For example, to print the serial number of a card in slot 2 of a controller at hostname “my-inst”, do the following:

slot2 = VTIREST('my-inst', 'slot0_2')
print(slot2.common.serial)
Parameters:

  • host – The hostname or IP address of the instrument.

  • slot – The slot name of the subinstrument. For non-modular products, the default of “inst0” should be used.

  • path – The subdirectory in the REST API to use.

  • members – The names of subdirectories and properties available at the specified path. This will be queried from the API if not specified.

  • session – The requests session to perform all HTTP operations with. Reusing the same session for all connections to the same host minimizes overhead.

_check_error()

Check the error queue for the connected instrument slot. If there is an item in the queue, it will be removed, and a VTIInstrumentError will be raised containing the details.

Raises:

jsonrest.VTIInstrumentError – The next item from the error queue, if any.

_child(name, members)

Construct a new VTIREST object representing a subdirectory of this one.

Parameters:

  • name – The name of the subdirectory

  • members – The names of items within the subdirectory

get(uri)

Perform a GET, querying the error queue and raising an exception if necessary.

Parameters:

uri – The URI to perform the GET on, relative to the base path of this object.

:return The message body of the response, converted from json to native python data types.

Raises:

jsonrest.VTIInstrumentError – When the HTTP status is 240, the next item in the instrument error queue will be raised as a child class of this type.

put(uri, data)

Perform a PUT, querying the error queue and raising an exception if necessary.

Parameters:

  • uri – The URI to perform the PUT on, relative to the base path of this object.

  • data – The data to send; it will be converted to JSON then included as the message body.

Raises:

jsonrest.VTIInstrumentError – When the HTTP status is 240, the next item in the instrument error queue will be raised as a child class of this type.

Indices and tables