Managing Graniitti API results
You can use query parameters in GET request to instruct the Frosmo back end to perform advanced processing on results.
Query parameters are appended to the request URL using the standard syntax of a question mark followed by the query string:
GET /users?fields=firstname
To define multiple values for a query parameter, use a comma-separated list:
GET /users?fields=firstname,lastname
To define multiple query parameters for the same request, use an ampersand as the delimiter:
GET /users?fields=firstname,lastname&lastname=user
Embedding
Certain resource types are related, such as companies and sites, segment groups and segments, and users and companies. In some cases, it can be useful to return not just the requested resources but also related resources. For example, when returning users, it may be useful to also return the companies to which they belong. Including related resources in a response is called embedding.
You can embed related resources using the includes query parameter. The parameter value is a comma-separated list of resource types. The related resources are included in the response as an array of objects (even when there's only one related resource) nested within each requested resource object.
The following example returns a user with their associated companies.
GET /users/584?includes=companies
{
"id": 584,
"firstname": "User",
"lastname": "User",
"email": "user.user@company.com",
"last_login": 2016-10-11T08:00:56+00:00,
"created": "2016-09-28T06:29:00+00:00",
"modified": "2016-09-28T06:29:00+00:00",
"role": "user",
"permission": "author",
"notify_via_slack": false,
"slack_username": null,
"companies": [
{
"id": 455,
"company": "Company",
"created": "2016-10-12 10:25:22",
"modified": "2016-10-12 10:25:22"
}
]
}
The following table shows which resource types (left column) can have which related resources types embedded with them (middle column).
The table lists only those resource types that have relations.
| Resource | Relation | Request |
|---|---|---|
Activity | User | |
Company | Site | |
Conversion definition | Trigger | |
Email campaign | Recommendation | |
Label | Modification | |
Modification | Label | |
Placement | Trigger | |
Segment | Segment group | |
Segment group | Segment | |
Shared code | Trigger | |
Site | Custom script | |
Trigger | Conversion definition | |
Placement Workspace placement | | |
Shared code Workspace shared code | | |
User | Company | |
Workspace | Workspace modification | |
Workspace placement | | |
Workspace shared code | | |
Workspace template | | |
Workspace trigger | | |
Workspace placement | Trigger Workspace trigger | |
Workspace shared code | Trigger Workspace trigger | |
Workspace trigger | Workspace placement | |
Filtering
You can filter results in the following ways:
Selecting which fields to return
You can select which fields are included in the response using the fields query parameter. The parameter value is a comma-separated list of fields to include. Fields that are not listed are excluded from the response.
The following example returns only the first name, last name, and email address of a user.
GET /users/584?fields=firstname,lastname,email
{
"firstname": "User",
"lastname": "User",
"email": "user.user@company.com"
}
Filtering with field values
The following fields support filtering directly with the field name:
-
Most integer fields
-
Most string fields (strings are not case-sensitive)
-
Boolean fields (you must use
0for false and1for true)
You cannot filter based on fields whose data type is an array or object.
For more information about which fields you can use for filtering with a given resource type, see the Graniitti API reference.
The following example returns users whose last name is "user" (in any case).
GET /users?lastname=user
[
{
"id": 584,
"firstname": "User",
"lastname": "User",
"email": "user.user@company.com",
"last_login": 2016-10-11T08:00:56+00:00,
"created": "2016-09-28T06:29:00+00:00",
"modified": "2016-09-28T06:29:00+00:00",
"role": "user",
"permission": "author",
"notify_via_slack": false,
"slack_username": null
},
{
"id": 585,
"firstname": "Power",
"lastname": "User",
"email": "power.user@company.com",
"last_login": 2016-10-02T10:44:21+00:00,
"created": "2016-09-28T06:33:11+00:00",
"modified": "2016-09-28T06:44:42+00:00",
"role": "user",
"permission": "author",
"notify_via_slack": false,
"slack_username": null
}
]
The following example returns sites that are active (with the is_active field set to true).
GET /companies/455/sites?is_active=1
[
{
"id": 1877,
"name": "company",
"company_id": 455,
"url": "http://company.com",
"created": "2016-10-12T07:27:12+00:00",
"modified": "2016-10-12T07:27:12+00:00",
"is_development": false
}
]
Filtering with FIQL
You can define advanced results filtering using the fiql and fiql_enc query parameters. You can use both parameters in the same request. The parameter values are Feed Item Query Language (FIQL) expressions. For more information about FIQL expressions and syntax, see the FIQL specification.
The parameters differ only in whether the API decodes reserved characters in the provided value:
-
The
fiqlparameter assumes a string value that is not percent-encoded. The API uses the value as is, meaning the API does not decode the value before using it to filter results.Use this parameter when the value doesn't need to be percent-decoded to make it valid FIQL. In other words, if the value doesn't represent FIQL operators or other syntactically meaningful characters in percent-encoded format, the value is usable as is. The value can still contain encoded reserved characters, such "%2C" for a comma in a field value, but since these do not break the FIQL syntax, the API does not need to decode them.
For example, the value
lastname==User%2C%20Jris a valid FIQL expression. The percent-encoded characters are part of a field value, so they don't need to be decoded. The encoding is nonetheless needed, since a comma and a space ("User, Jr.") would render the request URL invalid. -
The
fiql_encparameter assumes a string value that is percent-encoded. The API decodes the value with the PHPurldecode()function and uses the decoded value to filter results.Use this parameter when the value must be percent-decoded to make it valid FIQL. In other words, if the value represents FIQL operators or other syntactically meaningful characters in percent-encoded format, the value must be decoded to turn it into a usable FIQL expression. For encoding your FIQL expressions, you can use a site such as URL Decode and Encode.
For example, the value
lastname%3D%3DUser%252C%2520Jris an invalid FIQL expression. The equals operator ("==") is represented as percent-encoded characters ("%3D%3D"), which breaks the FIQL syntax. Decoding the value turns it intolastname==User%2C%20Jr, which is a valid FIQL expression.
The following example returns users whose last name is "User, Jr" (in any letter case, since a FIQL text search is case-insensitive). The example uses the fiql parameter, since the FIQL expression is not percent-encoded.
GET /users?fiql=lastname==User%2C%20Jr
[
{
"id": 587,
"firstname": "Power",
"lastname": "User, Jr",
"email": "user.user@company.com",
"last_login": 2016-10-11T08:00:56+00:00,
"created": "2016-09-28T06:29:00+00:00",
"modified": "2016-09-28T06:29:00+00:00",
"role": "user",
"permission": "author",
"notify_via_slack": false,
"slack_username": null
}
]
The following example returns the exact same data as the preceding example, but it uses the the fiql_enc parameter instead, since the FIQL expression is percent-encoded.
GET /users?fiql_enc=lastname%3D%3DUser%252C%2520Jr
Paginating
By default, results are not paginated, and requests that do not use pagination are limited to 10 000 results. If a request finds more than 10 000 results, the request returns an error. In this case, to get the results, use pagination.
You can enable pagination using the page parameter. The parameter value is the number of the page from which to return the results. The default page size is 100 results.
If you specify this parameter, the API returns the results only from the specified page. For example, if you set this parameter to 2, the API returns the results only from page 2, not up to page 2 or starting from page 2.
You can define a custom page size using the per_page parameter. The value is the number of results to return per page.
The response body for paginated results is an object with the following fields.
| Field | Type | Description |
|---|---|---|
| Number | Number of the page where the current results are from. |
| Array | Result data as an array of resource objects. |
| Number | Number of the first result on the current page. |
| Number | Number of the last page, that is, the total number of pages. |
| String | Request URL for the next page. If the current page is the last page, this field is set to info If you use other query parameters than |
| String | Request URL without any query parameters. |
| Number | Number of results per page. |
| String | Request URL for the previous page. If the current page is the first page, this field is set to info If you use other query parameters than |
| Number | Number of the last result on the current page. |
| Number | Total number of results for the request. |
The following example enables pagination for product results and returns the results from page 10. (The data field of the response body is ellipted for brevity.)
GET /sites/8/products?page=10
{
"current_page": 10,
"data": [
{
"site_id": 8,
"product_id": 901,
"product_id_string": "Cheetah Plushy (Big)",
"product_type": "Plushies",
"product_name": "Cheetah Plushy (Big)",
"created_at": "2017-10-01 12:50:00",
"updated_at": "2017-10-18 15:45:20"
},
{
"site_id": 8,
"product_id": 902,
"product_id_string": "Cheetah Plushy (Small)",
"product_type": "Plushies",
"product_name": "Cheetah Plushy (Small)",
"created_at": "2017-09-02 09:00:00",
"updated_at": "2017-10-03 20:20:18"
},
...
],
"from": 901,
"last_page": 25,
"next_page_url": "http://graniitti.domain.name/v0/sites/8/products?page=11",
"path": "http://graniitti.domain.name/v0/sites/8/products",
"per_page": 100,
"prev_page_url": "http://graniitti.domain.name/v0/sites/8/products?page=9",
"to": 1000,
"total": 2481
}
Sorting
By default, results are sorted in ascending order by resource ID.
You can define a custom sort order using the sort query parameter. The parameter value is a comma-separated list of fields to sort by. The results are first sorted by the first field, then by the second field, and so on.
You can sort the results in ascending or descending order per field:
-
To sort in ascending order, use the parameter value
<field_name>. -
To sort in descending order, use the parameter value
-<field_name>.
Most integer and string fields support sorting. You can also sort by Boolean fields, in which case false values (represented as 0) come before true values (represented as 1) in ascending order. You cannot sort by fields whose data type is an array or object.
For more information about which fields you can use for sorting with a given resource type, see the Graniitti API reference.
The following example sorts the returned users (each represented by a limited set of fields) in ascending order by last name. By default, the users are then sorted in ascending order by ID (as that's their order in the Frosmo database).
GET /users?fields=id,firstname,lastname&sort=lastname
[
{
"id:" 586,
"firstname:" "Project",
"lastname:" "Manager"
},
{
"id:" 584,
"firstname:" "User",
"lastname:" "User"
},
{
"id:" 585,
"firstname:" "Power",
"lastname:" "User"
},
...
]
The following example sorts the same users first in ascending order by last name and then in descending order by ID.
GET /users?fields=id,firstname,lastname&sort=lastname,-id
[
{
"id:" 586,
"firstname:" "Project",
"lastname:" "Manager"
},
{
"id:" 585,
"firstname:" "Power",
"lastname:" "User"
},
{
"id:" 584,
"firstname:" "User",
"lastname:" "User"
},
...
]