Where It Excels
tasks centered around single objects, eg. fetch a customer and some of their relationships - family members, registrations, invoices
tasks that require filtering of a collection. eg. fetch all events for a given date range.
Not So Much :)
tasks which require fetching thousands of records. When this is the primary object of the query, this is mitigated through paging. When the large collection is a relationship of a primary object, the collection is not paged and can cause out of memory exceptions and slow response times (will see improvements later)
Batch create & update. Currently we do not accept multiple objects in POST and PATCH requests. This requires each object be a separate request which can make batch updates slow and unwieldy.
Getting Started
The Api requires consumers to authenticate daily with a client id & secret. These keys can be managed through the Admin application by typing "API Keys" into the global search. When creating a new key, make sure to copy the secret since it is not accessible after creation.
After providing your credentials to our authentication endpoint you'll receive a fresh Json Web Token - see our API Docs for your versions authentication endpoint.
Pass this JWT as a bearer token in the Authorization Header when communicating with API endpoints. eg. `Bearer xxxxxxxx`
The Api follows the JsonApi Specification for communication with clients. You can find its documentation here. If you're looking to use our API, make sure to check out the available 3rd-party clients built on the JsonApi Spec. We also offer an official client written in PHP.
If you're looking for a list of our available endpoints, details about custom request parameters, or information on feature modules - Check out Rec Api documentation.
Creating API Keys
API Keys consist of a name, key, secret, audience, expiration date, and permissions.
When selecting permissions, a good practice is to only select those that are needed following The Principle of Least Privilege. Permissions are arranged by module and what actions are allowed for said modules with the number for each action being the number of resources that are allowed for that action under the module.
Secrets for API Keys should be kept secret as they are essentially passwords which includes using secure ways of sharing the credentials. For this, email can be dangerous so we recommend using something like One Time Secret. If you suspect that a key has been compromised, it is recommended that you delete the key and create a new one.
Examples
The system makes use of two custom request parameters which are not covered in the JsonApi Spec - filter and filterRelations:
filterRelations: A boolean parameter which specifies if filters targeting included relationships should also filter those relationships and not just the primary target of the query.
eg. In a query on customers:
/api/v1/customers?filter[signatures.waiver.is_active]=true&include=signatures.waiver&filterRelations=true
- filter to customers which have a signature on a valid waiver (filter[signatures.waiver.is_active]=true)
- include=signatures.waiver (will include customer signatures and the signed wavier)
Rows returned would include all signatures and waivers of customers that have signed an active waiver.
If we also query with filterRelations=true, You'll find only signatures on active waivers are returned.filter: A nested-object representing the where clause of a SQL statement.
There are two special concepts you can make use of in the filter param: grouping and operators.Grouping: You might want to write queries where your filters are more complicated than `filter[first_name]=John&filter[last_name]=Doe` You can accomplish this with filter groups using the `and` and `or` keywords - filter[or][0][first_name]=John&filter[or][1][first_name]=Jane.
Note: make sure to use numeric groups `[0]` after the `and` and `or` keywordsOperators: You may want to query with operators other than equals like: searching date ranges, matching an item in a collection, or matching part of a string.
To do this, you can post-fix filters with operators. They are specified like__[operator](two underscores)__gt (greater than),
__gte (greater than or equal),
__lt, (less than)
__lte, (less than or equal)
__in,
__notin,
__isnull,
__notnull,
__contains,
__starts,
__ends,