API Documentation | Tradetraks

Guide

Getting/Filtering Data

If the get endpoint is exposed to a resource, you can query for a collection of records for that resource.

Example

GET https://services.trade-traks.ca/api/User/get

FormData Parameters

Parameter	Type	Value
`filters`	JSON	JSON formatted array of filters. See Filters section below for more information
`include`	JSON	JSON formatted array of related resources to be sent with the result set.
`orders`	JSON	JSON formatted array of orders to determine sort order of the collection. Example: `[ ["first_name","ASC"], ["last_name", "DESC"] ]`
`fields`	JSON	JSON formatted array of field names. When this parameter is present, the collection results will only contain the fields specified. Example `["slug",first_name","last_name"]`
`page`	Integer	The current page to return in the result set. If not present, ALL records will be returned in most cases.
`custom_page_limit`	Integer	Allows you to set a custom page limit to over-ride the default number of records returned per page. Must be smaller than the default page setting.
`limit`	Integer	Allows you to limit the result set to a specified number of records.
`count`	Boolean	If set to true, a count property is returned which indicates the total number of records in the result set. No data is returned.

Example

GET https://services.trade-traks.ca/api/User/get?orders=[["first_name","ASC"]]&page=12

Including Related Resources

Related resources can be included within a parent collection, by using the include parameter. For example:

GET https://services.trade-traks.ca/api/Job/get with the following include parameter:

["User"]

Would return the following JSON structure:

{
	data: [
		{
			id: 321,
			job_name: "Lighting Installation",
			... (other job fields),
			User: [
				{
					id: 2,
					first_name: "Chad",
					last_name: "Tiffin",
					... (other user fields)
				}
			]
		}
	],
	success: true
}

Note the User property on the result object, which has been appended to each Job record in the collection.

You can also pass in nested parameters to included child collections like so:

include = [
	{
		model: "User",
		fields: ["slug","first_name","last_name"],
		include: ["ProfileImage"]
	}
]

NOTE: You can nest as deeply as needed, however be aware that deeply nested queries can significantly affect performance.

Sometimes there may be several relations of the same resouce on a record. For example, the Service resource owns multiple User child relations, that are attached using explicit keys to differentiate them: AssignedTo, UpdatedBy, WorkCompletedBy. Calling the User resource in an include to Service will attach all of these children relations to the record -- which may not be desirable for performance reasons.

Therefore you can use the omit key to pick and choose which relations of a specific resource you would like included:

include = [
	{
		model: "User",
		omit: ["WorkCompletedBy","AssignedTo"]
	}
]

Filters

Filtering is accomplished by sending a JSON formatted array of filters in filters parameter.

It accepts any of the following formats, in any combination:

To check if a field matches a given value:

[{field}, {value}]

To apply an operator other than equals (=):

[{field} {operator}, {value}]

Accepted operators:

If you wish to chain or statements together:

[{field}, {value}, 'or']

If you wish to make a LIKE comparison. SQL equivelant is LIKE '%value%':

[{field}, {value},'and/or','like']

To check if a given field is found in a set of given values:

[{field}, [{value1},{value2},...]]

These filters must be sent in a JSON formatted array, and can include any number or combination of filters:

Examples:

[
	["first_name", "Chad"],
	["first_name", "Jason","or"]
]

This is also equivalent to above:

[
	["first_name", ["Chad","Jason"]],
]

Looking for users between 18 and 65 with brown eyes:

[
	["age >", 18], //age must be greater than 18
	["age <=",65], //age must also be less than or equal to 65
	["eye_color","brown"] //eye_color must also be brown
]

If you're including related resources, you can also filter the parent collection by the contents of the included resource. For example, you may query the Job object, which has child User records. The following example would return only Job records with containing User records that match the given filters:

[
	["User.first_name","Chad"],
	["User.first_name","Chad","or","like"]
]

If you would like only records to be returned where ALL child records match a given condition, add a 4th parameter to the filter with match-all:

[
	["User.first_name","Chad"],
	["User.first_name","Chad","or",false,"match-all"]
]

You can can also filter for records that have NO child records attached to them:

[
	["User",false]
]

Filter Parameters Reference

Each filter accepts the following parameters:

[ {Field} {Operator} (optional), {Matching Value}, {Logical Operator} (optional), {Comparison Type}, {Matching Scheme}]

Parameter	Accepted Values	Example
Field (required)	{field_name} {childResource}.{field_name}	`[ ['name','Chad'] ]` Querying an included Child resource: `[ ['Contact.name','Chad'] ]` Match any possible values: `[ ['name',['Chad','Bill','Sam']] ]`
Operator	> >= < <= != If omitted, default is =	`[ ['regular_hours >',8] ]`
Matching Value (required)	String, Number, Array, Datetime String
Logical Operator	and or	`[ ['first_name','Chad'], ['last_name','Smith','and'] ]` `[ ['first_name','Chad'], ['first_name','Bob','or'] ]`
Comparison Type	like datetime	`[ ['first_name','Will','and','like'] ]` Will return all records with first_name field containing 'will' within the value. SQL equivelant of `WHERE first_name LIKE '%will%'` `datetime` parameter value only required when comparing datetime values on child Resources: `[ ['Locate.expiry','2023-06-12','and','datetime'] ]`
Matching Scheme	match-all Only for use when filtering by child resources. Leaving empty will return matches when any child matches the parameters	This will only return a result if All of the child Contact resource records have a name of 'Chad' `[ ['Contact.name','Chad','and',false,'match-all'] ]`

HTTP Verbs Finding a Single Record