Connect REST API Developer Guide

Connect REST API Developer Guide
Introduction
When to Use Connect REST API
Connect REST API Architecture
Connect REST API Limits
Build the Resource URL
Send HTTP Requests
HTTP Request Flow and a Response Body
Inputs and Binary File Upload Examples
Wildcards
Specify Response Sizes
filterGroup
exclude
include
Response Body Encoding
Status Codes and Error Responses
OAuth and Connect REST API
Perform Cross-Origin Requests from Web Browsers
Connect REST API Release Notes
API End-of-Life Policy
Quick Start
Work with Features
Examples
Resources
Chatter Resources
Request Bodies
Response Bodies
Appendices
PDF

Newer Version Available

This content describes an older version of this product. View Latest

include

To limit the response body to specific properties, use the include query string parameter.

The value for the include query string parameter is a list of properties separated by bars (|). You must URL encode the bars as %7C. Include a forward slash before every property name.

The following request includes only the aboutMe property and the address property in a response body:
1/chatter/users/me?include=/aboutMe%7C/address

The following table lists rules for using the include query parameter.

Description Original Output Include Value Filtered Output
Include a forward slash (/) before property names or the request returns an error. 
1{
2 "bar" : "bar value",
3 "baz" : "baz value"
4}
 include=bar 400 error with error code INVALID_FILTER_VALUE
Filter properties by name. 
1{
2 "bar" : "bar value",
3 "baz" : "baz value"
4}
 include=/bar 
1{
2 "bar" : "bar 
3value",
4}
Top-level properties are ignored. Note there is no error when you try this. 
1<foo>
2 <bar>bar value</bar>
3 <baz>baz value</baz>
4</foo>
 include=/foo 
1<foo>
2  <bar>bar value
3  </bar>
4  <baz>baz value
5  </baz>
6</foo>
Use a bar (|) delimiter to filter multiple properties. URL encode the delimiter as %7C. 
1{
2 "foo" : "foo value",
3 "bar" : "bar value",
4 "baz" : "baz value"
5}
 include=/foo%7C/bar 
1{
2  "foo" : "foo 
3value",
4  "bar" : "bar 
5value",
6}
Filtering a response body filters everything below it. 
1<foo>
2 <bar>bar value</bar>
3 <baz>baz value</baz>
4 <someObject>
5   <sub>sub 1</sub>
6 </someObject>
7</foo>
 include=/someObject 
1<foo>
2  <someObject>
3    <sub>sub 1
4    </sub>
5  </someObject>
6</foo>
To filter a property nested in a response body, include the parent response body name as a filter segment. 
1<foo>
2 <bar>bar value</bar>
3 <baz>baz value</baz>
4 <someObject>
5   <sub>sub value</sub>
6  </someObject>
7</foo>
 include=/someObject/sub 
1<foo>
2  <someObject>
3   <sub>sub 1
4   </sub>
5  </someObject>
6</foo>
Identify an item in a list by its property name. This example uses XML. 
1<foo>
2 <bar>bar valu</bar>
3 <baz>baz value</baz>
4 <someList>
5   <item>
6     <id>1</id>
7   </item>
8   <item>
9     <id>2</id>
10   </item>
11   <item>
12     <id>3</id>
13   </item>
14 </someList>
15</foo>
 include=/someList/item/id 
1<foo>
2 <someList>
3   <item>
4    <id>1</id>
5   </item>
6   <item>
7     <id>2</id>
8   </item>
9   <item>
10     <id>3</id>
11   </item>
12  </someList> 
13</foo>
Identify an item in a list by its property name. This example uses JSON. 
1{
2 "bar" : "bar value",
3 "baz" : "baz value",
4 "someList" : [
5   {
6     "id" : "1"
7   },
8   {
9     "id" : "2"
10   } ,
11   {
12     "id" : "3"
13   } 
14 ]
15}
 include=/someList/item/id 
1{
2 "someList" : [
3   {
4     "id" : "1"
5   },
6   {
7     "id" : "2"
8   } ,
9   {
10     "id" : "3"
11   } 
12 ] 
13}