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 and REST API support CORS (cross-origin resource sharing). To access these APIs from JavaScript in a Web browser, add the origin serving the script to the CORS whitelist. See Use CORS to Access Chatter REST API and 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.
If an application uses a session ID for authentication instead of an OAuth token, that application's requests count against a general quota of requests. All applications the user accesses with a session ID use this general quota. Because of this, we recommend clients use OAuth tokens.

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:

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.