User Tools

Site Tools


Sidebar

apiv4:field_filtering

Field Filtering

General

Web Services often return more data than required by any specific application in order to support the largest number of applications consuming them. This is problematic with bandwidth-limited devices, mobile platforms where resources are at a premium, and other devices simply wanting to be efficient. Field Includes/Excludes are the answer to this problem for the YouMail APIs.

Query Parameters

Two query parameters exist to control the fields returned in YouMail result sets. These fields accept a comma-separated list of values that represent elements in the result XML. These values use a dot notation form (which is essentially a simple path to the element).

  • fieldList - include the specified fields in the result XML (implicitly excluding all other fields). In comparison, “includeList” includes other attributes that you want to have returned in the result set in addition to the default list of attributes returned in a standard request. If “fieldList” is specified then only the attributes explicitly specified in the “fieldList” are returned. That means if a default field is not included in the “fieldList” then that default attribute is not returned in the result set.
  • excludeList - exclude the specified fields from the result XML (implicitly including all other fields, unless fieldList is being used to specify includes)

The parameters are in the form:

<rootElement>(.<childElement>)+

To reference firstName in a contact list XML result like the following:

<contacts>
  <contact>
    <id>123456</id>
    <firstName>Joe</firstName>
    <lastName>Blogg</lastName>
  </contact>
  <contact>
    <id>123457</id>
    <firstName>Jane</firstName>
    <lastName>Blogg</lastName>
  </contact>
</contacts>

You would use the following notation, which would apply to all firstName elements which are child elements of contact which are child elements of contacts:

contacts.contact.firstName

Examples

Including only specific fields

The follwing request

curl -H "Accept: application/xml" -X GET 'http://api.youmail.com/api/v3/contacts/506689?authtoken=TYvGnS2TrwC0pWFyyXsS6Ux1ndkduKnDbF6MgWY0YwOQ20BMuTbBOCAFBmcKaroXnPFgBfmhNH'

Results in the following Contact XML

<?xml version="1.0" encoding="UTF-8"?>
<contact>
  <id>123456</id>
  <createTime>2008-09-23T00:07:59Z</createTime>
  <blocked>false</blocked><contactGroups/>
  <emailAddress>test@blah.com</emailAddress>
  <firstName>Joe</firstName>
  <fullName>Joe Blogg</fullName>
  <homeNumber>0005557689</homeNumber>
  <inviteType>0</inviteType>
  <lastName>Crohn</lastName>
  <sortName>Raphael Crohn</sortName>
</contact>

Adding the follwing elements to the field list

curl -H "Accept: application/xml" -X GET 'http://api.youmail.com/api/v3/contacts?authtoken=GYvGnS2TrwC0pWFyyXsS6Ux1ndkduKnDbF6MgWY0YwOQ20BMuTbBOCAFBmcKaroXnPFgBfmhNH&fieldList=contacts.contact.id,contacts.contact.fullName'

Results in the following Contact XML

<?xml version="1.0" encoding="UTF-8"?>
<contact>
  <id>506689</id>
  <fullName>Raphael Crohn</fullName>
</contact>

As you can see, the second result is much more concise and will take less resources to process.

Excluding specific fields

The following request

curl -H "Accept: application/xml" -X GET 'http://api.youmail.com/api/v3/contacts/506689?authtoken=TYvGnS2TrwC0pWFyyXsS6Ux1ndkduKnDbF6MgWY0YwOQ20BMuTbBOCAFBmcKaroXnPFgBfmhNH'

Results in the following Contact XML

<?xml version="1.0" encoding="UTF-8"?>
<contact>
  <id>123456</id>
  <createTime>2008-09-23T00:07:59Z</createTime>
  <blocked>false</blocked><contactGroups/>
  <emailAddress>test@blah.com</emailAddress>
  <firstName>Joe</firstName>
  <fullName>Joe Blogg</fullName>
  <homeNumber>0005557689</homeNumber>
  <inviteType>0</inviteType>
  <lastName>Crohn</lastName>
  <sortName>Raphael Crohn</sortName>
</contact>

Adding the follwing elements to the field list

curl -H "Accept: application/xml" -X GET 'http://api.youmail.com/api/v3/contacts?authtoken=GYvGnS2TrwC0pWFyyXsS6Ux1ndkduKnDbF6MgWY0YwOQ20BMuTbBOCAFBmcKaroXnPFgBfmhNH&excludeList=contacts.contact.firstName,contacts.contact.lastName,contacts.contact.sortName'

Results in the following Contact XML

<?xml version="1.0" encoding="UTF-8"?>
<contact>
  <id>123456</id>
  <createTime>2008-09-23T00:07:59Z</createTime>
  <blocked>false</blocked><contactGroups/>
  <emailAddress>test@blah.com</emailAddress>
  <fullName>Joe Blogg</fullName>
  <homeNumber>0005557689</homeNumber>
  <inviteType>0</inviteType>
</contact>

Limitations

Currently, filters are only enabled for XML responses. JSON support will be added in the future.

apiv4/field_filtering.txt · Last modified: 2016/05/19 15:50 (external edit)

Page Tools