Responses

When an API finishes processing a request, it returns a response to indicate the outcome of the operation and provide the data to your application. Your application must know how to process that response, so that it can proceed.

Parts of a Response

API responses typically consist of several components. Each component conveys specific information from the server to the client. An API response consists of the following components.

  • HTTP Status Code. A three-digit value that indicates the outcome of the operation. For example, 200 or 404.

  • HTTP Headers. Contain metadata associated with the response. For example, content type, content length, caching directives, and server information. Headers provide additional context about the data being returned and any instructions for handling the response.

  • Body. Describes or contains the actual data or information of the requested action. In successful requests, the response body contains the data that the client asked for in a GET request, or indicates that resources have been added or changed for POST and PATCH requests. If there are problems with the client's request, it's common for the response body to describe why the request failed.
    Responses using a status code that answers the request without the need to include message content do not have a body. For Example 201 Created or 204 No Content.

  • Meta Information. Additional details about the response. For example, timestamps, pagination information for paginated responses, or links to related resources. Meta information helps clients understand the context of the response and navigate the API more effectively.

Example Response

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

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

HTTP Status Code 200

{
  "Id": "4261c758-31a0-438f-a7e8-9c5810757a1d",
  "Status": "RanToCompletion",
  "StatusUrl": "https://<OrgName>.<account>.am1.bartendercloud.com:<port>/api/actions/4421c297-31a0-435f-a7e8-8168184a1d"
  "Messages": [
    "[10/31/2024 9:29:13 AM]\t[Info]\tJob Status\r\n\r\nPrinter: Zebra_ZT420_(300_dpi)\r\nJob ID: 1\r\nStatus: Creating\r\nDescription: Application started creating the print job.",
    "[10/31/2024 9:29:13 AM]\t[Info]\tBarTender successfully sent the print job to the spooler.\r\n\r\nJob Name:TestTemplate\r\nDocument: TestTemplate\r\nPrinter: Zebra_ZT420_(300_dpi)",
    "[10/31/2024 9:29:04 AM]\t[Info]\tExecuting the 'Print Document' action."
  ]
}

Common Types of API Responses

API responses can be categorized by several common types, based on the status codes returned by the server.

  • Informational responses (100 – 199)

  • Successful responses (200 – 299)

  • Redirection messages (300 – 399)

  • Client error responses (400 – 499)

  • Server error responses (500 – 599)

The most common responses from the BarTender Cloud REST API are:

Type Status Definition Notes
Successful Response 2xx   These messages indicate that the request was successful and the server was able to process the request as expected.
  200 OK Standard response for successful HTTP requests. The result and meaning of success depends on the HTTP method:
    GET The resource has been fetched and transmitted in the message body.
   PATCH or POST The resource describing the result of the action is transmitted in the message body.
  201 Created Indicates that a new resource has been successfully created. This is typically the response sent after POST requests, or some PUT requests.
  204 No Content Indicates that the request was successful, but there is no content to return. The user agent may update its cached headers for this resource with the new ones.
Client Errors 4xx   These messages indicate that there was an issue with the client's request.
  400 Bad Request Indicates that The server cannot or will not process the request due to something that is perceived to be a client error (e.g., the request was malformed or contained invalid parameters).
  401 Unauthorized Indicates that the client is not authorized (i.e., "unauthenticated") to access the resource. The client must authenticate itself to get the requested response.
  403 Forbidden Indicates that the server understood the request but refuses to fulfill it. A server that wishes to make public why the request has been forbidden can describe that reason in the response content (if any).
If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client should not automatically repeat the request with the same credentials. The client may repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials.
An origin server that wishes to hide the current existence of a forbidden target resource may instead respond with a status code of 404 (Not Found).
  404 Not Found Indicates that the origin server could not find a current representation for the requested resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent
  405 Method Not Allowed Indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server generates an Allow header field in a 405 response containing a list of the target resource's currently supported methods.
  408 Request Timeout Indicates that the server did not receive a complete request message within the time that it was prepared to wait.
  409 Conflict Indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request.
Conflicts are most likely to occur in response to a PUT request.
Server Errors 5xx   These messages indicate that there was an error on the server side while processing the request.
  500 Internal Server Error Indicates that an unexpected condition was encountered on the server. This error is generic, signifying that the server cannot find a more appropriate 5XX status code to respond with.
  503 Service Unavailable Indicates that the server is currently unable to handle the request due to temporary overloading or maintenance, which may be alleviated after some delay. The server may send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.
Some servers might simply refuse the connection rather than send a 503 status code.
  507 Insufficient Storage Indicates that the method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request.

More Information

For more information about status codes, see the RFC 9110 specification.

Using the BarTender Cloud REST API