REST API Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Introduction to REST API
About REST API
Release Notes
Supported Editions and Required Permissions
REST Resources and Requests
REST API Architecture
Authorization Through Connected Apps and OAuth 2.0
Headers
Assignment Rule Header
Call Options Header
Compression Headers
Conditional Request Headers
Duplicate Rule Header
Limit Info Header
MRU Header
Package Version Header
Query Options Header
Warning Header
Send REST Requests with cURL
Valid Date and DateTime Formats
Status Codes and Error Responses
API End-of-Life Policy
Quick Start
Examples
Generating an OpenAPI 3.0 Document for sObjects REST API (Beta)
Reference
PDF

Conditional Request Headers

Use a conditional request header to validate resources before accessing them. By setting a precondition in the header, you ensure that your request succeeds only if that precondition is met. This functionality helps you prevent mistakes and reject outdated requests when updating Salesforce data. You can implement a variety of techniques with conditional request headers, such as response caching.

Two types of validation are available with conditional request headers: strong and weak. Strong validation checks whether the precondition exactly matches the resource in Salesforce. Strong validation headers include If-Match and If-None-Match, which use entity tags (ETags) to compare the precondition to the record in Salesforce.

Weak validation checks a precondition against the resource in Salesforce, but it doesn’t guarantee that the two are identical. Weak validation headers include If-Modified-Since or If-Unmodified-Since, which compare the precondition to the last modified date of the record in Salesforce.

REST API conditional headers follow the HTTP 1.1 specification with the following exceptions.
  • When you include an invalid header value for If-Match, If-None-Match, or If-Unmodified-Since on a PATCH or POST request, a 400 Bad Request status code is returned.
  • The If-Range header isn’t supported.
  • DELETE requests aren’t supported

ETag

The ETag header is a response header that’s returned when you access the sObject Rows resource. It’s a hash of the content that’s used by the If-Match and If-None-Match request headers in subsequent requests to determine if the content has changed.

This header is supported by sObject Rows (Account records only) resources.

This example shows an ETag returned by REST API.

ETag: "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

You can find the HTTP 1.1 specification for the ETag header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 .

If-Match

The If-Match header is a request header for sObject Rows that includes a list of ETags. If the ETag of the record that you’re requesting matches an ETag specified as a precondition in the header, the request is processed. Otherwise, a 412 Precondition Failed status code is returned, and the request isn’t processed.

This header supports sObject Rows (Account records only) resources.

In this example an, If-Match header is included with a request.

If-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

You can find the HTTP 1.1 specification for the If-Match header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24 .

If-None-Match

The If-None-Match header is a request header for sObject Rows that’s the inverse of If-Match. If the ETag of the record that you’re requesting matches an ETag specified in the header, the request isn’t processed. A 304 Not Modified status code is returned for GET or HEAD requests, and a 412 Precondition Failed status code is returned for PATCH requests.

This header supports sObject Rows (Account records only) resources.

In this example, an If-None-Match header is included with a request.

If-None-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

You can find the HTTP 1.1 specification for the If-None-Match header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26 .

If-Modified-Since

The If-Modified-Since header is a time-based request header. The request is processed only if the data has changed since the date and time specified in the header. Otherwise, a 304 Not Modified status code is returned, and the request isn’t processed.

This header supports sObject Rows, sObject Describe, Describe Global, and Invocable Actions resources.

In this example an If-Modified-Since header is included with a request.

If-Modified-Since: Tue, 10 Aug 2015 00:00:00 GMT

You can find the HTTP 1.1 specification for the If-Modified-Since header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25 .

If-Unmodified-Since

The If-Unmodified-Since header is a request header that’s the inverse of If-Modified-Since. If you make a request and include the If-Unmodified-Since header, REST API processes the request only if the data hasn’t changed since the specified date. Otherwise, a 412 Precondition Failed status code is returned, and the request isn’t processed.

This header supports sObject Rows, sObject Describe, Describe Global, and Invocable Actions resources.

In this example, an If-Unmodified-Since header is included in a request.

If-Unmodified-Since: Tue, 10 Aug 2015 00:00:00 GMT

You can find the HTTP 1.1 specification for the If-Unmodified-Since header at www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28 .