API Basics

The Jetstream API adheres to REST architectural principles and utilizes JSON as its data-interchange format.

The Jetstream API enables you, a developer, to configure and query your Terso RFID devices and Jetstream application – allowing you to create impressive new applications or quickly enhance existing applications with RFID inventory tracking and management capabilities. In short,

Jetstream API + Terso RFID Devices + Your Application

=

Increased Business Value

The base URL for this version of the Jetstream API is https://jetstream.tersosolutions.com/3. Note the current version number in the URL, as well as the new domain name.

All requests to the Jetstream API must be made over HTTPS with TLS 1.1 or higher. HTTP requests and HTTPS requests using TLS 1.0 or earlier will not work.

All requests to the Jetstream API require authentication via a user access key. In the request header, set a 'AccessKey' key with your user access key as the value. A user access key is provided during user account sign up and is associated to a Jetstream application. A user access key is unique to a user and should be securely stored.

The Jetstream API accepts and sends data as JSON. For endpoints that send JSON data, define the header request’s ‘Content-Type’ key with a value of ‘application/json’.

The below HTTP verbs are used by the Jetstream API.

Verb Description
POST Create a new resource.
GET Read/retrieve a resource.
PUT Update/replace a resource.
DELETE Delete a resource.
PATCH Delete a resource.

The Jetstream API returns data as JSON.

The below HTTP status codes are used by the Jetstream API.

Status Code Description
200 OK

Successful GET, PUT, and POST requests pertaining to:

  • Reading/retrieving resources
  • Updating/replacing resources
  • Configuring resources (e.g., set a device’s configuration parameters, update firmware, add and/or remove passes)
  • Commanding resources (e.g., restart a device, lock a device, unlock a device, execute a proprietary command)
201 Created

Successful POST requests pertaining to:

  • Creating new resources
  • Configuring resources (e.g., adding a policy to a device)
204 No Content

Successful DELETE requests pertaining to:

  • Deleting resources
  • Configuring resources (e.g., removing a policy from a device)

Note: No message body is returned.
400 Bad Request

Pertains to:

  • Requests with errors (e.g., malformed syntax, missing required parameters, invalid parameter values)
  • Requests failing due to conditions not being met
  • Requests failing due to an invalid URI

Note: See the error message(s) given in the response message body for more details.
401 Unauthorized

Pertains to:

  • Requests failing due to a missing or invalid access key
404 Not Found

Pertains to:

  • Requests failing due to the requested resource not existing or not being found
  • Requests failing due to the resource(s) relating to the requested resource not existing or not being found – see the error message(s) given in the response message body for more details
  • Requests failing due to an invalid URI
500 Internal Server Error Something went wrong on our end – we do our best to avoid these situations. Try your request again later. If this error persists, please contact us.

Searching and/or sorting allows you to slim down the returned data, ensuring you only focus on the data you need.

Search and/or sort large result sets via passing parameters in the URL by including a query string. The details for each query type are outlined below.

Sort can be used on its own, separate from search, as follows:

In this example, we will be using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort by the "name" property. Here’s how to do so:

https://jetstream.tersosolutions.com/3/devices?sort=name

Notes

  • The "https://jetstream.tersosolutions.com/3/devices" section of the URL indicates the Get All Devices endpoint.
  • The "?" separator indicates the start of the query string used for searching.
  • The “name” value is a property of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
  • The returned results will contain devices ordered by their "name" property, in ascending order.

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort, first, by the "devicedefinition" property and, then, by the “region” property. Here’s how to do so:

https://jetstream.tersosolutions.com/3/devices?sort=devicedefinition,region

Notes

  • The "https://jetstream.tersosolutions.com/3/devices" section of the URL indicates the Get All Devices endpoint.
  • The "?" separator indicates the start of the query string used for searching.
  • The "devicedefinition" and "region" values are properties of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
  • The "," character is used to separate multiple values. There should be no space following the comma.
  • The returned results will contain devices ordered by their "devicedefinition" property first, and then, by their "region" property within each "devicedefinition", in ascending order.

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort by the “name” property, in descending order. Here’s how to do so:

https://jetstream.tersosolutions.com/3/devices?sort=-name

Notes

  • The "https://jetstream.tersosolutions.com/3/devices" part of the URL indicates the Get All Devices endpoint.
  • The "?" separator indicates the start of the query string used for searching.
  • The "-" character is used to sort the results in descending order – it must precede the value.
  • The "name" value is a property of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
  • The returned results will contain devices ordered by their "name" property, in descending order.

In this example, we will continue using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application and sort, first, by the "devicedefinition" property and, then, by the "region" property, in descending order. Here’s how to do so:

https://jetstream.tersosolutions.com/3/devices?sort=-devicedefinition,-region

Notes

  • The "https://jetstream.tersosolutions.com/3/devices" section of the URL indicates the Get All Devices endpoint.
  • The "?" separator indicates the start of the query string used for searching.
  • The "-" character is used to sort the results in descending order – it must precede each value.
  • The "devicedefinition" and "region" values are properties of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
  • The "," character is used to separate multiple values. There should be no space following the comma.
  • The returned results will contain devices ordered, first, by their "devicedefinition" property and, then, by their "region" property within each "devicedefinition", in descending order.

Search and sort can be used together as follows:

In this example, we will be using the Get All Devices endpoint. Suppose you want to find all devices in your Jetstream application containing the name "beer" and sort by the "region" property. Here’s how to do so:

https://jetstream.tersosolutions.com/3/devices?name=beer&sort=region

Notes

  • The "https://jetstream.tersosolutions.com/3/devices" section of the URL indicates the Get All Devices endpoint.
  • The "?" separator indicates the start of the query string used for searching.
  • The "name" parameter is a property of the Device resource. Not all properties of a resource are searchable. See the Parameters table for each endpoint to determine which properties are searchable.
  • The "&" character is used to separate multiple parameters. There should be no spaces preceding nor following the ampersand. In this case, it separates the search and sort parts of the query.
  • The "region" value is a property of the Device resource. Not all properties of a resource are sortable. See the Parameters table for each endpoint to determine which properties are sortable.
  • The returned results will contain devices with a name containing AND equal to "beer", ordered by their “region” property, in ascending order.

The key is to combine the search and sort parts of the query via the "&" character. Above is only one possible combination of search and sort to create a query. Reference the separate search and sort possibilities and combine them to create even more ways to search and sort.