Queries

An API query is a request to a server to retrieve data from an API. The request is made by sending an HTTP request to a specific endpoint URL. HTTP requests are messages formatted in the HTTP protocol that are sent from a client to a server capable of responding to them. The messages are formatted using standardized HTTP protocol syntax. Each request initiates an action on the target server, which gives a response as an answer. The response from the server is usually in JSON format.

DOES THE BTC REST API USE LOGIC AND/OR CONDITIONAL OPERATORS? Dynamic date variables? Sort operator? URL Parameters?

The mechanics of a request/query are simple:

The client requests data using the following HTTP syntax: [HTTP Method] https://[OrgName].am1.bartendercloud.com/[api]/[endpoint]?[optional parameters]
The server then returns a response, which indicates the outcome of the operation and provides the data to your application.

HTTP GET and POST are the two most commonly used HTTP methods to exchange information between a client and a server. The BarTender Cloud REST API uses the GET, POST, and PATCH methods.

For more information about the GET, POST, and PATCH methods, see HTTP Call Type Definitions.

Parts of a Query

Request Header

HTTP headers contain metadata in key-value pairs and are sent with HTTP requests and responses. Request headers are sent by the client to the server. They contain information and instructions related to the requested resource. Some common headers are:

Accept. Defines the media types that the client is able to accept from the server.
Authorization. Used to send the client’s credentials to the server when the client is attempting to access a protected resource.
Content-Type. Identifies the media type of the content in the request body to the server.

Query Parameters

Query parameters are variables passed to an API endpoint by a query. These parameters provide specific instructions for the API to process. Query parameters are added to the end of the URL and are used to filter, sort, or modify the data being returned by the API. Query parameters are separated from the URL by a question mark (?) and from other query parameters by an ampersand (&). For example:

https://organization.am1.bartendercloud.com/api/devices/printers?modelName=Zebra_105SL&mustHaveAllSpecifiedPermissions=true

The BarTender Cloud API does not accept spaces in queries. So, if you want to use the printer model Zebra 105SL as a query parameter, you must insert an underscore in the name: Zebra_105SL.

Request Body

The request body is data sent by the client to the server and contains the actual data that is required to create, update, or delete a resource.

Example Query

To illustrate endpoints, queries, and responses we'll be looking at a sequence from Postman.

This is the initial query: sending a .BTW document to a printer to print.

https://[OrgName].am1.bartendercloud.com/api/actions?Wait=30s
{
  "PrintBTWAction": {
    "Document": "librarian://Main/Templates/TestTemplate.btw",
    "Printer": "Zebra_ZT420_(300_dpi)",
    "Name": "Test Template Print",
    "Description": "Desc",
    "SaveAfterPrint": false,
    "QueueAndContinue": false,
    "VerifyPrintJobIsComplete": true,
    "ReturnPrintSummary": true
  }
}

In the query above, the Print Action PrintBTWAction is used to print a BarTender document.

The parameters listed below PrintBTWAction define the properties of the document to be printed (including the specific location of the .BTW file), the printer to be used, and any other actions taken during the request (defined as either true or false).