REST API Developer Guide
jNewer Version Available
Using Conditional Requests
To support response caching, REST API allows conditional request
headers that follow the standards defined by the HTTP 1.1 specification.
For strong validation, include either the If-Match or
If-None-Match header in a request, and reference the entity
tags (ETag) of the records you want to match against. For weak validation, include either the
If-Modified-Since or If-Unmodified-Since header in a request along with the date and time you want to check
against. The 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 are not supported with these headers.
- ETag
- HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19
- 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.
- Supported resources: SObject Rows (account records only)
- Example: ETag: "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"
- If-Match
- HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24
- The If-Match header is a request header for SObject Rows that includes a list of ETags. If the ETag of the record you’re requesting matches an ETag specified in the header, the request is processed. Otherwise, a 412 Precondition Failed status code is returned, and the request isn’t processed.
- Supported resources: SObject Rows (account records only)
- Example: If-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"
- If-None-Match
- HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26
- 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 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.
- Supported resources: SObject Rows (account records only)
- Example: If-None-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"
- If-Modified-Since
- HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25
- 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.
- Supported resources: SObject Rows, SObject Describe, Describe Global, and Invocable Actions
- Example: If-Modified-Since: Tue, 10 Aug 2015 00:00:00 GMT
- If-Unmodified-Since
- HTTP 1.1 specification: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28
- 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, the request is processed 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.
- Supported resources: SObject Rows, SObject Describe, Describe Global, and Invocable Actions
- Example: If-Unmodified-Since: Tue, 10 Aug 2015 00:00:00 GMT