Chatter REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

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

Chatter REST API Architecture

To use Chatter REST API, understand a few fundamental characteristics of its architecture, like how to authenticate, what the request limits are, and which data formats it supports.
These are important characteristics of Chatter REST API resources and architecture:
Authentication
Chatter REST API uses OAuth 2.0.

Salesforce is generally accessed securely, that is, using HTTPS.

Note

CORS (Cross-Origin Resource Scripting)
Chatter REST API supports CORS (cross-origin resource sharing). To access this API from JavaScript in a Web browser, add the origin serving the script to the CORS whitelist. See Use CORS to Access Chatter REST API.
Default HTML entity encoding
Chatter REST API strings are minimally HTML entity encoded by default, which is suitable in most cases for display between HTML tags, but not necessarily in other HTML contexts.

For non-HTML contexts, such as native mobile applications, Chatter REST API clients may request raw (unencoded) output by setting the X-Chatter-Entity-Encoding HTTP header in your request to false.

For more information, see Response Body Encoding.

JSON and XML support
The JavaScript Object Notation (JSON) format is supported with UTF-8. Date-time information is in ISO8601 format.
XML serialization is similar to SOAP API. XML requests are supported in UTF-8 and UTF-16, and XML responses are provided in UTF-8.
Responses are in JSON format by default. To specify XML, use the HTTP header Accept: application/xml. (To specify JSON, use Accept: application/json.)
You can append either .json or .xml to the URI of any resource to specify how the return is formatted. For example, /chatter/feeds/filter/me/001/feed-elements.xml.

Not all features support XML.

Note

Limits
Chatter REST API requests are subject to rate limiting. Chatter REST API has a per user, per application, per hour rate limit. When you exceed the rate limit, all Chatter REST API resources return a 503 Service Unavailable error code for both the user and application.
If an application uses a regular session ID for authentication instead of an OAuth token, that application's requests count against a general allocation of requests where there is no associated OAuth consumer key.  However, any other application the user accesses, that is also authenticating with session IDs, is contending for the same allocation of requests. For example, your app connects a user to Salesforce using a regular session ID. This user now has the same number of requests regardless of the app they are using. They no longer have a separate request limit per application: all applications are now using the same limit. Because of this, we recommend clients use OAuth tokens whenever feasible.

Stated limits aren't a promise that the specified resource is available at its limit in all circumstances. For example, load, performance and other system issues might prevent some limits from being reached. The stated limit may change without notice. Applications should make efficient use of available requests and gracefully handle the 503 error code.

Note

Localized names and times
Chatter REST API localizes both the names and datetimes to the locale setting of the user. Users set their locale in their personal information. If the user hasn’t set their locale, Chatter REST API uses the default locale for the organization.
Clients can use any locale available in the organization to override the default locale. Use the Accept-Language HTTP header to override the locale for any API request.

ISO-8601 dates are always in GMT.

Note

Salesforce ID length
Salesforce IDs in response bodies are always 18 character IDs. In request bodies, you can use either 15 character IDs or 18 character IDs.
UI Themes
Clients can use the X-Connect-Theme HTTP header to specify a UI theme for any API request. There are two themes, each with their own set of motif icons: Classic and Salesforce1. Theme names are case sensitive.
Method overriding
If you use an HTTP library that doesn’t allow overriding or setting an arbitrary HTTP method name, you can send a POST request and provide an override to the HTTP method with the request parameter _HttpMethod. For example:
1https://instance_name/services/data/v32.0/chatter/
2/chatter/users/me/conversations/03MD0000000008KMAQ
3?_HttpMethod=PATCH&read=true

The _HttpMethod parameter is case sensitive. Be sure to use the correct case for all values.

Note

Stateless
Each request from client to server must contain all the information necessary to understand the request, and not use any stored context on the server. However, the representations of the resources are interconnected using URLs that allow the client to progress between states.
Uniform interface
All resources are accessed with a generic interface over HTTP.