The Trak Software API supports the following HTTP methods for interacting with resources:
Request | Description |
---|---|
GET | Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they’re safe and idempotent. |
POST | Use a POST request to create new resources. For example, make a POST request to the account endpoint where the body of your request JSON is a new account. |
PUT | Use a PUT request to create or update a resource. For example, alter an account name by passing it in the request body. |
DELETE | Make a DELETE request to remove a resource. |
{primary} If your ISP doesn’t permit HTTP operations other than GET or POST, use HTTP Method tunneling: make your call with POST, but include the method you intend to use in an X-HTTP-Method-Override header.
The Trak Software API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PUT requests require a valid JSON object for the body. The API Reference includes complete examples, but here’s a quick look at the JSON format we’re looking for in POST and PUT requests:
{
"name": "Example Account",
"status_id": 1,
"notifications": true
}
There are 3 main categories of parameters for each endpoint in the Trak Software API: path, query string, and request body. The API Reference includes a list of all available parameters for each possible request, but these sections offer an overview of the 3 main categories and their subcategories.
In an API URL, we include resource names and unique identifiers to help you figure out how to structure your requests. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your Trak Software account. Let’s look at an example:
https://example.trak.io/api/v1/accounts/{account_id}/users/{user_id}
In that URL, there is 1 primary resource, accounts, and 1 subresources: users. There are also 2 different path parameters that you need to replace with real values from your Trak Software account: account_id and user_id. When you replace those values with actual data, your final URL should look something like this:
https://example.trak.io/api/v1/accounts/1/users/101
We use query string parameters for filtering, pagination, and joining resources in the Trak Software API. The format for query string parameters is the full resource URL followed by a question mark, and the optional parameters:
Filtering
The API Reference shows you which resources you can filter on, and what to include in your URL query string. For example, to view only active acounts, pass the active=true
query parameter. If you provide multiple filters, we only return resources that match all filters.
https://example.trak.io/api/v1/accounts?search=foobar&active=true
Parameter Type | Description |
---|---|
Array | All filter parameters that indicate that include an Array prior to another parameter type, have the option to either pass an array or the parameter type, or a single parameter. |
Boolean | Allows multiple truthy\falsy values including true |false , 0 |1 , or "yes" |"no" |
DateRange | Array of two timestamps. start and end . |
integer | Interger value without single or double quotes. |
String | String value. |
Pagination
Paginate your API requests to limit response results and make them easier to work with. Our pagination method utilizes paging, passing the limit
and page
query parameters to filter down the dataset. Limit set the amount of resources to return, and page dynamically sets the offset. The page defaults to 1, so if you use page=2
, you’ll receive the next set of resources from the dataset. Limit defaults to 50. For example, this URL includes query string parameters for pagination:
https://example.trak.io/api/v1/accounts?page=1&limit=50
Joining Resources
Some endpoints allow you to request extra information by joining other resources to the response. For example, you can request the author of an account by passing with=author
to the GET request. To also receive the author's avatar, you can simply pass with=author.avatar
, and the response will include both the author and their avatar. To join several resources, seperate the resources with a pipe |
character.
https://example.trak.io/api/v1/accounts?with=author.avatar|logo
For POST and PUT requests, you may need to include a request body in JSON format. The API Reference shows you all the available request parameters for each endpoint, including required fields. The following example shows you how to create a new account with an HTTP POST request using curl (note the format of the --data option).
curl --request POST \
--url 'https://example.trak.io/api/v1/accounts' \
--header 'content-type: application/json' \
--header 'Authentication: Bearer <api_key>' \
--data '{"name":"New Account", "status_id": 1, "notifications": true}'