API Basics

overview the jetstream api enables you, a developer, to configure and query your https //www tersosolutions com/search all sensors/ and jetstream application – allowing you to quickly enhance your business applications with rfid inventory tracking and management capabilities navigating the api documentation the page tree on the left helps you quickly jump between different sections and pages you can quickly flip between jetstream api versions using the version selector in the page tree main provides the documentation for v3, and you can use the selector to view the documentation for jetstream v2 the table of contents on the right helps you quickly jump between different sections within the current page the search bar in the top right can be used to search on any content, on any page, for any version of the api the api basics page contains everything you need to know about how to get requests to and responses from jetstream, along with reference information like version changes and a glossary the openapi documentation for jetstream docid 3iuriinzplfzdui4xgjcu page contains the openapi documentation for jetstream, including instructions on how to use this documentation and the latest json for the api the device types docid 0mdmv9mheyzodrera8n7x section tells you more about the various types of terso rfid devices that can be managed via jetstream, including their commands, configuration parameters, logentryevents, and sensors the api endpoints docid\ ukj5qmjrcpvfwbyxxm5wy section contains detailed documentation of the various jetstream api command and configuration endpoints, including descriptions, parameters, examples, and version changes the event types docid rl8govwbokktttojfnn5 section contains descriptions, parameters, examples, and version changes for all events jetstream may return in a get events call exploring jetstream with postman postman is a powerful tool that allows easy testing and experimenting of apis to start using jetstream in postman, first download https //www getpostman com/downloads/ and install postman here is a guide on how to create a postman collection using the swagger json https //www c sharpcorner com/article/import swagger apis into postman collection/ https //www c sharpcorner com/article/import swagger apis into postman collection/ see the openapi documentation for jetstream docid 3iuriinzplfzdui4xgjcu page for a link to the json tools a net sdk and service base are available on github https //github com/tersosolutions additional resources release notes docid 2 avche h6pe9b78vqfiw jetstream workflow guides docid\ ntbft1mbgs3tfxaybqsfa how it works jetstream facilitates communication between your remotely deployed terso rfid device types docid 0mdmv9mheyzodrera8n7x and your application that consumes jetstream messages between your jetstream application and your application that consumes jetstream messages let’s take a look at each communication path in more detail communication with your terso rfid device a remotely deployed terso rfid device initiates communications on its own as well as responds to communications from api requests jetstream will, then, publish the event to the events queue of your jetstream application your application can, then, retrieve the queued events, via a get events docid\ exupifhp3manjooqyjsiz api request how your application uses the events is up to the business logic you’ve coded in for example, the information extracted from a heartbeatevent event could be used to update when a device last communicated and, thus, could serve as an indication that the device has internet connectivity this information would be useful on a devices dashboard your application can communicate with a terso rfid device via command api requests since jetstream supports many different terso rfid devices, each with its own unique capabilities, device definitions are used to define the commands and configuration values each device supports in jetstream for example, to query for a device’s current network configuration, a get a device's policy parameters docid\ g6s4nzg5dsgaf dcagbtb command api request can be made when a command request is made, jetstream determines if the device is online if the device is online, the command is executed immediately is offline, the command is queued in jetstream for the device to pick up and execute the next time it establishes communications or polls for queueable commands once a command is executed, if the command is synchronous, results are returned immediately and can be viewed in the response body if there is no issue executing the command, the output parameter list will be populated with data, if applicable to the command is an issue executing the command, exceptions will appear in the exception list is not synchronous, results are published and can be viewed in a commandcompletionevent docid\ sj1tshbqvf4fri6az1ywg event, via get events docid\ exupifhp3manjooqyjsiz the commandcompletionevent event is published to the events queue of your jetstream application after the command executes if there is no issue executing the command, the output parameter list will be populated with data, if applicable to the command is an issue executing the command, exceptions will appear in the exception list the most common command exception is "command timed out" if a command is not retrieved by a device within 24 hours (1,440 minutes), jetstream will clear the command from the queue and return this exception in the commandcompletionevent docid\ sj1tshbqvf4fri6az1ywg in the end, your application will work with a combination of command responses and commandcompletionevent docid\ sj1tshbqvf4fri6az1ywg to complete communications with a terso rfid device communication with your jetstream application whereas command api requests are meant to communicate with your terso rfid devices, configuration api requests are meant to communicate with your jetstream application configuration api requests allow you to manage and maintain the resources (e g , devices, device definitions, policies, events) pertaining to your jetstream application within your jetstream application, you can create a device docid\ p7nz8balv5 rd8s82wh5d , create a policy docid\ ovolmlpoo8ofxhva59lws , add a policy to a device docid 8iinkl mz80hpiut5zv2e , get all devices docid\ arlgha4yu a2jgsmh6ln3 , and more get events docid\ exupifhp3manjooqyjsiz , which has already been mentioned above, is also a configuration api request when making a configuration api request, results are returned immediately and can be viewed in the response body request base url the base url for this version of the jetstream api is https //api jetstreamrfid 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 2 or higher http requests and https requests using tls 1 1 or earlier will not work authentication 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 data format 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’ http verbs 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 for best results, remember to url encode any special characters in your request parameters response 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 , creating, modifying, or deleting device credentials, aliases) commanding resources (e g , restart a device, lock a device, unlock a device) 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 https //www tersosolutions com/contact us/ search & sort searching and sorting allow you to slim down and arrange the returned data, ensuring you only focus on the data you need search and sort large result sets via passing parameters in the url by including a query string the details for each query type are outlined below search search can be used on its own, separate from sort, as follows in this example, we will be using the get all devices docid\ arlgha4yu a2jgsmh6ln3 endpoint suppose you want to find all devices in your jetstream application containing the name "terso" here’s how to do so https //api jetstreamrfid com/3/devices?name=terso notes the "https //api jetstreamrfid 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 returned search results will contain devices with a name containing and equal to "terso" what if you wanted to find all devices in your jetstream application containing the names "terso" and "solutions"? it’s possible and here’s how to do so https //api jetstreamrfid com/3/devices?name=terso,solutions notes the "," character is used to separate multiple values there should be no space following the comma the returned search results will contain devices with a name containing and equal to "terso" and devices with a name containing and equal to "solutions" search on multiple properties in this example, we will continue using the get all devices docid\ arlgha4yu a2jgsmh6ln3 endpoint suppose you want to find all devices in your jetstream application containing the name "terso", the serial number "1234", and the region "us" here’s how to do so https //api jetstreamrfid com/3/devices?name=terso\&serialnumber=1234\&region=us notes the "https //api jetstreamrfid 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", "serial number", and "region" parameters are all properties 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 or following the ampersand the returned search results will contain devices with a name containing and equal to "terso" and devices with a serial number containing and equal to "1234" and devices with a region containing and equal to "us" what if you wanted to find all devices in your jetstream application containing the names "terso" and "solutions", the serial numbers "1234" and "4321", and the regions "us" and "ap"? it’s possible and here’s how to do so https //api jetstreamrfid com/3/devices?name=terso,solutions\&serialnumber=1234,4321\&region=us,ap notes the "," character is used to separate multiple values there should be no space following the comma the returned search results will contain devices with a name containing and equal to "terso" and devices with a name containing and equal to "solutions" and devices with a serial number containing and equal to "1234" and devices with a serial number containing and equal to "4321" and devices with a region containing and equal to "us" and devices with a region containing and equal to "ap" in this example, we will continue using the get all devices docid\ arlgha4yu a2jgsmh6ln3 endpoint suppose you want to find all devices in your jetstream application not containing the name "terso" here’s how to do so https //api jetstreamrfid com/3/devices?name=!terso notes the "https //api jetstreamrfid 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 exclude results it must precede the value to be excluded the returned search results will contain devices with names that do not contain or are not equal to "terso" what if you wanted to find all devices in your jetstream application not containing the names "terso" and "solutions"? it’s possible and here’s how to do so https //api jetstreamrfid com/3/devices?name=!terso,solutions notes the "!" character is used to exclude results it must precede the first value to be excluded, and you only need one "!" before all excluded values the "," character is used to separate multiple values there should be no space following the comma the returned search results will contain devices with a name neither containing nor equal to "terso" and devices with a name neither containing nor equal to "solutions" in this example, we will continue using the get all devices docid\ arlgha4yu a2jgsmh6ln3 endpoint suppose you want to find all devices in your jetstream application that do not contain the name "terso", the serial number "1234", and the region "us" here’s how to do so https //api jetstreamrfid com/3/devices?name=!terso\&serialnumber=!1234\&region=!us notes the "https //api jetstreamrfid 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", "serial number", and "region" parameters are all properties 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 exclude results it must precede the first value to be excluded, and you only need one "!" before all excluded values the "&" character is used to separate multiple parameters there should be no spaces preceding or following the ampersand the returned search results will contain devices with a name neither containing nor equal to "terso" and devices with a serial number neither containing nor equal to "1234" and devices with a region neither containing nor equal to "us" what if you wanted to find all devices in your jetstream application that do not contain the names "terso" and "solutions", the serial numbers "1234" and "4321", and the regions "us" and "ap"? it’s possible and here’s how to do so https //api jetstreamrfid com/3/devices?name=!terso,solutions\&serialnumber=!1234,4321\&region=!us,ap notes the "!" character is used to exclude results it must precede the first value to be excluded, and you only need one "!" before all excluded values the "," character is used to separate multiple values there should be no space following the comma the returned search results will contain devices with a name neither containing nor equal to "terso" and devices with a name neither containing nor equal to "solutions" and devices with a serial number neither containing nor equal to "1234" and devices with a serial number neither containing nor equal to "4321" and devices with a region neither containing nor equal to "us" and devices with a region neither containing nor equal to "ap" sort sort can be used on its own, separate from search, as follows in this example, we will be using the get all devices docid\ arlgha4yu a2jgsmh6ln3 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 //api jetstreamrfid com/3/devices?sort=name notes the "https //api jetstreamrfid 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 sort on multiple properties in this example, we will continue using the get all devices docid\ arlgha4yu a2jgsmh6ln3 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 //api jetstreamrfid com/3/devices?sort=devicedefinition,region notes the "https //api jetstreamrfid 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 sort descending on one property in this example, we will continue using the get all devices docid\ arlgha4yu a2jgsmh6ln3 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 //api jetstreamrfid com/3/devices?sort= name notes the "https //api jetstreamrfid 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 sort descending on multiple properties in this example, we will continue using the get all devices docid\ arlgha4yu a2jgsmh6ln3 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 //api jetstreamrfid com/3/devices?sort= devicedefinition, region notes the "https //api jetstreamrfid 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 & sort search and sort can be used together as follows in this example, we will be using the get all devices docid\ arlgha4yu a2jgsmh6ln3 endpoint suppose you want to find all devices in your jetstream application containing the name "terso" and sort by the "region" property here’s how to do so https //api jetstreamrfid com/3/devices?name=terso\&sort=region notes the "https //api jetstreamrfid 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 "terso", 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 version changes what's new? modified endpoints create a device docid\ p7nz8balv5 rd8s82wh5d delete a device docid\ tv8yyt3i9lfwcx jurqmi get a device docid\ zpamtaaf4vcd4eamucpfc get all devices docid\ arlgha4yu a2jgsmh6ln3 new endpoints modify a device docid\ ucpbzffrcws0h zjf4ovp create an alias docid\ cstsab cv6ogqwmtuaql modify an alias docid\ nl75i4z2qkopklpmdra2e delete an alias docid h9nzpmiiivcdaxi7lq5e get an alias docid\ mm2q6kdqrkq87e9hd8z4 get all aliases docid\ ov3aylvxcdddqdhf0bnzt get all alias names docid 6 wme69v3dpwio4qyo8fd create device credentials docid y xfsvux fyloqyuzqmr modify device credentials docid\ j3ncv3riuibv506 jobzd delete device credentials docid 6bj1etryzo paajn3zasg get device credentials docid\ x1 nubzlpevnels9beq17 sync device credentials docid\ l7ik ra1wcy3phhm0fwqs get last device credentials sync date/time docid\ xcfht1rs4l0m0ssfmpz8e modified events objectevent docid 6kkkdbv1sxgpehyq9dh0j new events aliasaddedevent docid\ nzfmxjoj3idqopb5cd no aliasmodifiedevent docid 1o1u3i0jroevsutg 8qp6 aliasremovedevent docid\ lllzxp7rcot6pnpo43nzu deviceaddedevent docid\ bi2z5 siwyl1qen5dtde7 devicemodifiedevent docid\ ngbuuheky9w3u pswbjlq deviceremovedevent docid\ qc1qfkfj1zas we2vbdb4 devicecredentialsaddedevent docid\ z1bocp0xiluzg zwdand7 devicecredentialsmodifiedevent docid 9bim1dwlfus 9ayfamfds devicecredentialsremovedevent docid\ qh8sfnvxius 5pgzzns0h what’s been replaced? endpoint (versions 2) replacement endpoint (version 3) get all passes docid\ d7j1rxbgyehbv3bajwgsp get device credentials docid\ x1 nubzlpevnels9beq17 add or remove passes docid\ the3s6mtw3baeauul1a83 create device credentials docid y xfsvux fyloqyuzqmr , delete device credentials docid 6bj1etryzo paajn3zasg , sync device credentials docid\ l7ik ra1wcy3phhm0fwqs replace all passes docid\ qp6qihbmdr1a 9kr7fekj modify device credentials docid\ j3ncv3riuibv506 jobzd event (versions 2) replacement event (version 3) logicaldeviceaddedevent docid\ abxaz3sjowc4tv9qri6fe deviceaddedevent docid\ bi2z5 siwyl1qen5dtde7 logicaldeviceremovedevent docid\ y1gvw v2xpu zzek6s6ee deviceremovedevent docid\ qc1qfkfj1zas we2vbdb4 what’s been deprecated? execute a proprietary command