Connect REST API Developer Guide

Connect REST API Developer Guide
Introduction
When to Use Connect REST API
Connect REST API Architecture
Connect REST API Rate 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
Response Body Encoding
Status Codes and Error Responses
OAuth and Connect REST API
Perform Cross-Origin Requests from Web Browsers
Quick Start
Work with Features
Examples
Resources
Request Bodies
Response Bodies
Appendices
PDF

Newer Version Available

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

Inputs and Binary File Upload Examples

Make HTTP POST, PATCH, and PUT requests using inputs and learn more about uploading binary files.

Using POST, PATCH, or PUT for Input

When you make a request using the HTTP POST, PATCH, and PUT methods, you can use request parameters or a request body. The request body can contain JSON or XML. If you pass resource-specific request parameters and a request body, the request parameters are ignored. Request parameters that aren’t specific to a resource, such as parameters in a bearer token URL and the _HttpMethod parameter, are processed along with the request body. Use bearer token parameters as they are. Don’t add or remove parameters.

To submit a request using request parameters, use a Content-Type header field with the value application/x-www-form-urlencoded.

To submit a request using a request body, use one of the following values in a Content-Type header field and in an Accept header field:
  • application/json
  • application/xml

Uploading Binary Files

To upload a binary file up to 2 GB (including headers), up to 75 MB for an external repository, or up to 512 MB for bulk conversations, send it as a body part in a multipart/form-data request. You can send the text of a comment (but not a post) as a JSON or XML rich input body part in the same multipart/form-data request. Alternately, you can choose to send that information in request parameters. If you pass both a rich input request body and request parameters, the request parameters are ignored.

In version 36.0 and later, you can’t create a feed post and upload a binary file in the same request. Upload files to Salesforce first, and then use the file IDs to attach one or more files to a feed post.

Important

To create a multipart/form-data request, in the head of the request, set the Content-Type HTTP header to multipart/form-data.

For information about HTTP headers, see W3C Form content types, and RFC 2388, which defines the multipart/form-data internet media type.

This table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-data request:

HTTP Headers for Rich Input Body Part Header Value and Parameters Description
Content-Disposition form-data; name="json"

form-data; name="xml"

 The request body for a post or comment.

For JSON, the value of name use "json".

For XML, the value of name use "xml".
Content-Type application/json; charset=UTF-8

application/xml; charset=UTF-8

 The data format and character set of the request body.

For JSON, the value must be application/json.

For XML, the value must be application/xml.

Web browsers are typically incapable of making multipart requests when the non-binary parts, such as rich input bodies, have their own Content-Type. To work around this issue, specify a certain Content-Disposition name and Salesforce can read the Content-Type of the rich input part. (You don’t have to specify a Content-Type for the rich input body.)

Tip

This table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-data request from a web browser:
HTTP Headers for Rich Input Body Part from Web Browser Header Value and Parameters Description
Content-Disposition form-data; name="feedElement"

form-data; name="comment"

form-data; name="photo"

form-data; name="file"

 To post a feed element with a binary file (in version 35.0 and earlier), the value of name must be "feedElement".

To post a comment with a binary file, the value of name must be "comment".

To upload an employee, user, or group photo, the value of name must be "photo".

To upload a file to the Files home or an external repository, the value of name must be "file".

This table describes the HTTP headers and parameters required in the binary upload body part of a multipart/form-data request:

HTTP Headers for Binary Upload Body Part Header Value and Parameters Description
Content-Disposition form-data; name="feedElementFileUpload"; filename=string To post a feed element with a binary file (in version 35.0 and earlier), the value of name must be "feedElementFileUpload".

To post a comment with a binary file, the value of name must be "feedElementFileUpload".
form-data; name="fileUpload" filename=string To upload a user or group photo, the value of name must be "fileUpload".
form-data; name="fileData" filename=string To upload a file to the Files home or to upload a file to an external repository, the value of name must be "fileData".

Specify a filename parameter and value. However, Salesforce uses the value of the title property of the File Input or the metadata of the Files Connect Item Input as the file name, not the value of the filename parameter.

Note
form-data; name="audioFileData" filename=string To upload an audio file, the value of name must be "audioFileData".
Content-Type application/octet-stream; charset=ISO-8859-1 The media type and character set of the binary file.

Spacing and carriage returns and line feeds (CRLF) are important. For example, this line requires spaces: Content-Disposition: form-data; name="feedItemFileUpload"; title="2012_q1_review.ppt". If you had used CRLF instead of spaces, you would have received an error.

Note

Post a feed element with a binary file (version 35.0 and earlier)

This example uses the /chatter/feed-elements resource to post a new feed item (which is a type of feed element), upload a binary file, and attach it to the new feed item. This example uses cURL.
Here is the same example in a different format so you can see the request body parts.

Post a batch of feed elements with binary files (version 35.0 and earlier)

This example uses the /chatter/feed-elements/batch resource to post a batch of feed elements, upload two binary files, and attach them to the feed elements in the batch. Include the information about the binary parts in the request body. This example uses cURL.
Here is the same example formatted to show the request body parts.

The binary part names in the binaryPartNames properties must match the binary part names in the name properties of the binary request parts.

Note

Post a comment with a binary file

This example uses the /chatter/feed-elements/feedElementId/capabilities/comments/items resource to post a comment to a feed item and upload a binary attachment using cURL.
Here is the sample example formatted to see the request body parts.

Post multiple comments with binary files

This example is a generic batch request to /connect/batch that contains two subrequests. Each subrequest comments on a feed item and uploads a binary file to the comment.

Include the request body of each subrequest in the richInput properties.

Also include information about the binary parts in the binaryPartName and binaryPartNameAlias properties.

Here is the cURL example.
Here is the multipart/form-data request body.

Upload and crop a user photo

This example uses the /connect/user-profiles/userId/photo resource to upload a user profile photo and crop it using cURL.
Here is the same example formatted to see the request body parts.

Upload a file to the Files home

This example uses the /connect/files/users/userId resource to upload a file to the Files home using cURL.
Here is the same example formatted to see the request body parts.

Upload a file to an external repository

This example uses the /connect/content-hub/repositories/repositoryId/folders/repositoryFolderId/items resource to upload a file to an external repository using cURL.
Here is the same example formatted to see the request body parts.

Upload an audio file

This example uses the /voicecalls/voiceCallId/audio_upload resource to upload an audio file using cURL.