Jump to: Fields | Filter | Sort | Limit and Page for Pagination | ID and IDs for Record Identification | Parameters ‘key’ and ‘display’ for Choices | Model_data for Actions Save and Validate | Related Entities | Term for Autocomplete
The power of these features is harnessed through the following API call parameters:
- Common Parameters:
- Parameter ‘fields
- Parameter ‘filter
- Parameter ‘sort
- Parameters ‘limit‘ and ‘page‘
- Parameters ‘id‘ and ‘ids‘
- Parameters ‘key‘ and ‘display‘
- Parameter ‘model_data‘
- Parameter ‘related_entities‘
- Parameter ‘term‘
Fields
For those familiar with SQL, a field parameter is analogous to a SELECT statement, which is how you define the data you want returned for the entity. This parameter is also the mechanism by which you can get related data about an entity without having to do a secondary API call.
The fields parameter accepts a comma-separated value (CSV) list or array of field names to include, which can be the fields of the entity or related entity and/or their fields. The following examples demonstrate how to use the fields parameter in your API calls.
Parameter &fields is available for actions:
- find.json
- find_by_ids.json
- get.json
Assume you’re working with the /advertiser/campaigns entity:
Example 1 – Getting a subset of entity fields parameters
To limit the result to only return specific fields then set the fields parameter to a comma separated array of the specific fields you’d like returned.
fields=id,name,site_id
When the API includes the above, it would return results below:
{ id:1, name:"campaign1", advertiser_id: 3 }
Example 2 – Getting all entity fields
To get all entity fields set the value of fields to an asterisk.
fields =*
When the API includes the above, it would return results below:
{ id:1, name:"campaign1", advertiser_id: 3, ..., ..., ..., all fields }
Example 3 – Include all fields of related entity
To include all fields of a related entity simply include the entity name or include * after entity.
fields =id,name,advertiser
– or –
fields=id,name,advertiser.*
In addition to the entities fields specified, this parameter also returns all fields of the related advertiser entity.
{ id:1, name:"campaign1", advertiser: { id:3, name:"advertiser3", ..., ..., all advertiser fields } }
Example 4 – Include subset of related entity fields
To include only a subset of related entity fields, simply include the specific fields after the related entity name separated by a period.
fields=id,name,advertiser.id,advertiser.name
In addition to the entities fields specified, this parameter also returns the two fields of the related advertiser entity.
{ id:1, name:"campaign1", advertiser: { id:3, name:"advertiser3" } }
Filter
For those familiar with SQL, a filter parameter is analagous to a WHERE clause.
Parameter &filter is available for actions:
- choices.json
- count.json
- find.json
Filter Fields
You can include fields to filter for both the entity that you’re working on, as well as its related entities (similar to the fields parameter).
Comparison Operators
Support comparison operators:
- =
- >
- >=
- <
- <=
- IN
- BETWEEN
- LIKE
Multiple Filters
You can combine filters using the AND and OR operators.
Assume you’re working with the /advertiser/campaigns entity:
Example 1 – Field equals value
To filter where a field equals a value set the filter parameter accordingly. Note that the operator = needs to be URL encoded.
filter=(status = ‘active’)
This parameter returns only the campaigns where the status field is active.
Example 2 – Related entity field equals value
You can use related entities as the filter field by referencing them appropriately.
filter=(publisher.name = ‘Ad Network 123′)
This parameter returns the campaigns where the related publisher has a name of Ad Network 123.
Example 3 – Using IN and AND
You can use the in operate like a select statement and include a comma separated array in ( ).
filter=(publisher_id in (1,2,3,4)) AND (status = ‘active’)
This parameter returns the campaigns where both the publisher_id = 1,2,3, or 4 AND status of the publishers is active.
Sort
The sort parameter determines the order in which results are returned.
Parameter sort is available for actions:
- choices.json
- find.json
The examples below assume you’re working with the advertiser/campaigns entity.
Example 1 – single field sort
To sort by a single field simply include the field for the sort parameter. This sorts ascending.
sort=name
This parameter returns the campaigns by campaign name in alphabetical order (from A to Z).
Example 2 – Single field descending (aka reverse) sort
To sort descending include a colon followed by “desc” after the sort field.
sort=name:desc
This parameter returns the campaigns by campaign name in reverse alphabetical order (from Z to A).
Example 3 – Multi field sort
You can sort by multiple fields by including them in a comma separated array.
sort=advertiser_id,name:desc
This parameter returns the campaigns by advertiser id (name) in reverse alphabetical order (from Z to A).
Limit and Page for Pagination
This parameter restricts the number of results to send back. Default value is 10
Pagination parameters limit and page are available with these actions:
ID and IDs for Record Identification
Parameter &id is used by these actions and must reference an identifier of an existing record:
- delete.json
- get.json
Parameter &ids is used by this action and must reference an identifier of an existing record:
- find_by_ids.json
Parameters ‘key’ and ‘display’ for Choices
Model_data for Actions Save and Validate
Parameter ‘data’ is associated with type ‘model_data’.
Related Entities
Term for Autocomplete
Parameter ‘term’ used with Action ‘autocomplete’ searches for a match within values of its Endpoint’s auto-completion column that starts with provided string of characters, case insensitive. Typical fields assigned to auto-completion column are:
- ‘name’
- ’email’
- ‘value’