Use query strings with GET requests to control the data that is returned.
Use the appropriate regional endpoint to ensure that you comply with your organization's privacy policy, and applicable laws and regulations. For details about the available regional endpoints, and how to identify your organization's region, see Shared responsibility.
Fields
The
fields query string parameter can be used to specify
precisely what fields are returned for a resource. This parameter is valid for
both instance and collection responses.
Example
You want to request that only the
id and
name fields are returned for a Member Variable in
the response.
To create this request, append the URL with the
fields query string after the resource
(memberVariable):
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?fields=id,name
For details about the
/membervariable resource, see
Member Data Service.
Paging
When requesting large amounts of data, you can group the results into
smaller chunks. When used together, the
limit and
offset query string parameters allow you to
effectively page through the results. This parameter is valid for
collection responses only.
| Parameter | Description |
|---|---|
limit
|
The maximum number of items that will be returned per page in the response. The default is 20 and the maximum is 1000. |
offset
|
The number of items that were skipped for the current page of results. |
Example
You want the response to return 40 items per page. To do this:
- Append the URL after the
resource (
memberVariables) with thelimitparameter set to return the first 40 items and theoffsetparameter set to start with the first item (?limit=40&offset=0).https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?limit=40&offset=0 - Create another request
to return the next 40 results beginning at the 41st item
(
?limit=40&offset=40).https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?limit=40&offset=40 - Continue to create
requests until the total number of items has been reached.
See the Response Payload section on how to determine the total number of items.
Sorting
Use the
sort query string parameter to sort the data in
ascending or descending order.
This parameter is valid for Collection responses only.
The query string format is as follows:
/{resource}?sort={fieldName}:{a|d}
The following table describes the query string components:
| Component | Description |
|---|---|
{resource}
|
The name of the resource. |
{fieldName}
|
The name of the field you would like the results sorted on. |
{a|d}
|
Refers to ascending (a) or descending (d) sorts. The default sorting order is ascending. |
?sort=effectiveDate,lastUpdateDate
Example
You want to sort the
name field on the
memberVariables resource in descending order. To do
this append
?sort=name:d to the URL after the resource:
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?sort=name:d
See
Member Data
Service for details on the
memberVariables resource.
Filtering
You can filter your results for specific values. Filtering is valid for Collection responses only. The format is as follows:
GET
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/{resource}?{fieldA}={valueA}&{fieldB}={valueB}
The following describes the components of the query string:
| Component | Description |
|---|---|
{resource}
|
The name of the resource. |
{fieldA}
|
The name of the fields to filter on. |
{fieldB}
|
|
{valueA}
|
The single values or comma-separated lists of values to match. |
{valueB}
|
Filter example
You want your request to only return Member Variables that have a
name of
email or
city. To do this, append the email and city fields
(?name=email,city) to the end of the URL after the resource
(/membervariables).
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/memberVariables?name=email,city
See
Member Data
Service section for details on the
memberVariables resource.
Depending the on the endpoint, you can filter the response on an array of nested fields.
Filter on an array example
You want to filter the concepts in a dataset based on the question
type in the
tags field. To do this, append the field name to the
end of the URL followed by
.contains and the field value.
GET
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/datasets/{datasetId}/concepts?q=%22tags.contains(%22singlechoice%22)%22
You can also use the query string parameter
q to build complex conditions to filter on a specific
value, values in a range, or a combination of conditions.
Query string example
If today's date is November 16, 2016, then the following request will return all the activities that are scheduled to be closed today or thereafter.
GET
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/activities?q="closedOn>="2016-11-16T00:00:00Z""
q does not work, encode its value in the URL. Using
the above URL example, the encoded version will be:
https://api.{region}.alida.com/v1/applications/{communityApiKeyName}/activities?q=%22closedOn%3E%3D%222016-11-16T00%3A00%3A00Z%22%22
For more information, see HTML URL Encoding Reference.
The following table lists the operations supported by the parameter
q:
| Operation type | Operation name | Operators | Example |
|---|---|---|---|
| Equality | Equal |
= or
eq or
%3D
|
?q="status="open""
|
| Not Equal |
!= or
neq or
%21=
|
?q="status neq "open""
|
|
| Less than |
< or
lt or
%3C
|
?q="closedOn<"2016-11-16T00:00:00Z""
|
|
| Less than or equal |
<= or
le or
%3C=
|
?q="closedOn le
"2016-11-16T00:00:00Z""
|
|
| Greater than |
> or
gt or
%3E
|
?q="closedOn>"2016-11-16T00:00:00Z""
|
|
| Greater than or equal |
>= or
ge or
%3E=
|
?q="closedOn ge
"2016-11-16T00:00:00Z""
|
|
| Logic | Intersection of results |
and
|
?q="openedOn>="2016-11-01T00:00:00Z" and
openedOn<"2016-12-01T00:00:00Z""
|
| Union of results |
or
|
?q="status="pending" or
status="open""
|
|
| String | Match from the end |
{field}.EndsWith("{match string}")
|
?q="name.EndsWith("test")"
|
| Contains |
{field}.Contains("{match
string}")
|
?q="name.Contains("satisfaction")"
|
|
| Match from the beginning |
{field}.StartsWith("{match
string}")
|
?q="name.StartsWith("2016")"
|
Headers
Use headers to authenticate the API and return an entity.
| Header | Description |
|---|---|
X-WebApi-Return-Resource
|
If the value of this header is set to
true then the entity (or entities) will be
returned in the response payload for POST, PUT and PATCH requests.
If
|