Glossary

Here are some key terms you'll find in the documentation and what they mean:

API Key

As explained by AWS, an API key is an alphanumeric string used to control access to an API. In the case of Garmat API, it's a 128-character long string that is associated to an account and allows developers to operate with that account's resources.

The keys are also used to identify who is making what requests, and to apply rate limiting, for instance.

Query parameters

Query parameters are a type of parameter that can be included in some requests. You can identify which endpoints support these parameters and what parameters they support because they will have a Query parameters section in their documentation.

What distinguishes this type of parameters is that they are included directly in the URL that is being requested.

To include them in a request, they must be added to the URL, separated by a question mark ? character. And they are included as key-value pairs, separated by an equal sign, like:

https://my-url.com/some-endpoint?param=value

If you want to include more than one query parameter in the same request, they must be separated by an ampersand &, like:

https://my-url.com/some-endpoint?param1=value1&param2=value2

Path parameters

Like query parameters, path parameters are a special type of parameter that is allowed for some endpoints. You can identify which endpoints support these parameters and what parameters they support because they will have a Path parameters section in their documentation.

Unlike query parameters, path parameters don't use a key-value format, but only the value. like:

https://my-url.com/param_value

This is typically used to include some slug or ID that uniquely identifies some resource being accessed.

These two types of parameters are not mutually exclusive. Some endpoints support both path and query parameters.

Body

Body is yet another way to include data in a request, similar to query and path parameters.

Body is typically included with POST, PUT and PATCH operations.

The format of the body will change depending on the API. But for Garmat API, all endpoints that support a body use JSON format, and as such, it's recommended to set the Content-Type header of requests to application/json.

You will identify which endpoints in the API support a body, and what parameters must be included in it because there will be a Body section in their documents. For these, you will also find an example of a well-formatted request in the examples section under Request examples.

ISO8601 formatting

You will find that some of the fields in the request or response of some endpoints state that ISO8601 format is used.

ISO8601 is a popular way of formatting strings, in the form YYYY-MM-DD HH:mm:ss.sssZ, where Y is the year, M is the month, D is the day, H is the hour, m is the minute, and s is the seconds and microseconds. Z is used to indicate that the timezone is UTC. The format supports specifying a timezone as well, but for Garmat API all timestamps are in UTC, so that's not required. Here's an example ISO8601 formatted timestamp representing Aug 24, 2024 at 05:30 a.m. in UTC:

2024-08-24 05:00:00Z

CSV

CSV is a commonly used data format to store table-like data.

CSV files can contain or not a header, and then the rest of the rows will be data rows.

The CSV files produced by the export_csv endpoint do include a header row.

Here's a quick example of what a CSV file could look like:

id,name,age,title
abc123,John Doe,29,Operations Manager
abc124,Jane Doe,35,Senior Analyst

Here, the first row contains the headers: id, name, age, and title. And the second and third rows contain data, of one person each.

Stages

You'll come across the term 'stages' or 'modes' in this documentation. Both of them mean the same. A stage represents a mode that a booth was in. The different modes that booths can be in are:

  • Spray Mode
  • Bake Set Pt 1
  • Bake Set Pt 2
  • Bake Set Pt 3
  • Purge Mode
  • Cycle Complete
  • Cool Down
  • Booth Off