REST API Developer Guide Version 43.0, Summer ’18 @salesforcedocs Last updated: July 30, 2018 © Copyright 2000–2018 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners. CONTENTS Chapter 1: Introducing Lightning Platform REST API. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Lightning Platform REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Using Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Using Conditional Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Using cURL in the REST Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Understanding Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Defining Connected Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Understanding OAuth Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Understanding the Web Server OAuth Authentication Flow . . . . . . . . . . . . . . . . . . . . . . 7 Understanding the User-Agent OAuth Authentication Flow. . . . . . . . . . . . . . . . . . . . . . 12 Understanding the Username-Password OAuth Authentication Flow. . . . . . . . . . . . . . . 15 Understanding the OAuth Refresh Token Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Finding Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Use CORS to Access Salesforce Resources from Web Browsers. . . . . . . . . . . . . . . . . . . . . . 20 Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Step One: Obtain a Salesforce Developer Edition Organization . . . . . . . . . . . . . . . . . . . . . . 22 Step Two: Set Up Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Step Three: Send HTTP Requests with cURL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Step Four: Walk Through the Sample Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Using Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Chapter 3: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Getting Information About My Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 List Available REST API Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 List Organization Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 List Available REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Get a List of Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Get an Image from a Rich Text Area Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Get a List of Objects If Metadata Has Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Working with Object Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Retrieve Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Get Field and Other Metadata for an Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Get Object Metadata Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Working with Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Create a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Update a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Delete a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Contents Get Field Values from a Standard Object Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Get Field Values from an External Object Record by Using the Salesforce ID. . . . . . . . . . 46 Get Field Values from an External Object Record by Using the External ID Standard Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Retrieve a Record Using an External ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Insert or Update (Upsert) a Record Using an External ID . . . . . . . . . . . . . . . . . . . . . . . 48 Traverse Relationships with Friendly URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Get Attachment Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Get a List of Deleted Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 57 Get a List of Updated Records Within a Given Timeframe. . . . . . . . . . . . . . . . . . . . . . . 58 Working with Searches and Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Execute a SOQL Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Execute a SOQL Query that Includes Deleted Items. . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Get Feedback on Query Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Search for a String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Get the Default Search Scope and Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Get Search Result Layouts for Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 View Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Insert or Update Blob Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Working with Recently Viewed Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 View Recently Viewed Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Mark Records as Recently Viewed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Managing User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Manage User Passwords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Working with Approval Processes and Process Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Get a List of All Approval Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Submit a Record for Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Approve a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Reject a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Bulk Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Get a List of Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Get a Particular Process Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Trigger Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Using Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Describe Event Monitoring Using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Query Event Monitoring Data with REST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Get Event Monitoring Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Download Large Event Log Files Using cURL with REST. . . . . . . . . . . . . . . . . . . . . . . . . 89 Delete Event Monitoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Query or View Hourly Event Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Using Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Execute Dependent Requests in a Single API Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Update an Account, Create a Contact, and Link Them with a Junction Object. . . . . . . . . 96 Update a Record and Get Its Field Values in a Single Request. . . . . . . . . . . . . . . . . . . . 97 Contents Create Nested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Create Multiple Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Chapter 4: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Resources by Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Describe Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 SObject Basic Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 SObject Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 SObject Get Deleted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 SObject Get Updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 SObject Named Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 SObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 SObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 SObject Blob Retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 SObject ApprovalLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 SObject CompactLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Describe Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 SObject PlatformAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 SObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 SObject Rich Text Image Retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 SObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 SObject Suggested Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 SObject User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Platform Event Schema by Event Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Platform Event Schema by Schema ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 AppMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Compact Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Standard Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Custom Invocable Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 List View Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 List View Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Support Knowledge with REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Data Category Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Data Category Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Articles List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Articles Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Parameterized Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Process Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Product Schedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Contents Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 QueryAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Recent List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Recently Viewed Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Record Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Record Count Response Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Retrieve Knowledge Language Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Search Scope and Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Search Result Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Search Suggested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Search Suggested Article Title Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Search Suggested Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 SObject Tree. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 SObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Assignment Rule Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Call Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Limit Info Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Package Version Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Query Options Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Status Codes and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 CHAPTER 1 Introducing Lightning Platform REST API In this chapter ... REST API provides a powerful, convenient, and simple Web services API for interacting with Lightning Platform. Its advantages include ease of integration and development, and it’s an excellent choice of • Lightning Platform technology for use with mobile applications and Web 2.0 projects. If you have many records to process, REST Resources consider using Bulk API, which is based on REST principles and optimized for large sets of data. • Using Compression REST API uses the same underlying data model and standard objects as those in SOAP API. See the SOAP • Using Conditional API Developer Guide for details. REST API also follows the same limits as SOAP API. See the Limits section Requests in the SOAP API Developer Guide. • Using cURL in the To use the API requires basic familiarity with software development, web services, and the Salesforce REST Examples user interface. • Understanding Use this introduction to understand: Authentication • Use CORS to Access • The key characteristics and architecture of REST API. This will help you understand how your Salesforce Resources applications can best use the Lightning Platform REST resources. from Web Browsers • How to set up your development environment so you can begin working with REST API immediately. • How to use REST API by following a quick start that leads you step by step through a typical use case. 1 Introducing Lightning Platform REST API Lightning Platform REST Resources Lightning Platform REST Resources A REST resource is an abstraction of a piece of information or an action, such as a single data record, a collection of records, or a query. Each resource in REST API is identified by a named Uniform Resource Identifier (URI) and is accessed using standard HTTP methods (HEAD, GET, POST, PATCH, DELETE). REST API is based on the usage of resources, their URIs, and the links between them. You use a resource to interact with your Salesforce org. For example, you can: • Retrieve summary information about the API versions available to you. • Obtain detailed information about a Salesforce object, such as Account, User, or a custom object. • Perform a query or search. • Update or delete records. Suppose you want to retrieve information about the Salesforce version. Submit a request for the Versions resource. curl https://yourInstance.salesforce.com/services/data/ The output from this request is as follows. [ { "version":"20.0", "url":"/services/data/v20.0", "label":"Winter '11" } ... ] Note: Salesforce runs on multiple server instances. The examples in this guide use yourInstance in place of a specific instance. Replace that text with the instance for your org. Important characteristics of the Lightning Platform REST API resources and architecture: 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, which allow the client to progress between states. Caching behavior Responses are labeled as cacheable or non-cacheable. Uniform interface All resources are accessed with a generic interface over HTTP. Named resources All resources are named using a base URI that follows your Lightning Platform URI. Layered components The Lightning Platform REST API architecture allows for the existence of such intermediaries as proxy servers and gateways to exist between the client and the resources. Authentication The Lightning Platform REST API supports OAuth 2.0 (an open protocol to allow secure API authorization). See Understanding Authentication for more details. 2 Introducing Lightning Platform REST API Using Compression Support for JSON and XML JSON is the default. You can use the HTTP ACCEPT header to select either JSON or XML, or append .json or .xml to the URI (for example, /Account/001D000000INjVe.json). 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. Friendly URLs Why make two API calls when you can make just one? A friendly URL provides an intuitive way to construct REST API requests and minimizes the number of round-trips between your app and Salesforce org. Friendly URLs are available in API version 36.0 and later. Accessing a contact’s parent account without a friendly URL involves requesting the contact record using the SObject Rows resource. Then you examine the account relationship field to obtain the account ID and request the account record with another call to SObject Rows. Using a friendly URL, you can access the account in a single call directly from the contact’s path: /services/data/v36.0/sobjects/contact/id/account. This functionality is exposed via the SObject Relationships on page 126 resource. For more examples of using friendly URLs to access relationship fields, see Traverse Relationships with Friendly URLs on page 51. Using Compression The REST API allows the use of compression on the request and the response, using the standards defined by the HTTP 1.1 specification. Compression is automatically supported by some clients, and can be manually added to others. Visit Salesforce Developers for more information on particular clients. Tip: For better performance, we suggest that clients accept and support compression as defined by the HTTP 1.1 specification. To use compression, include the HTTP header Accept-Encoding: gzip or Accept-Encoding: deflate in a request. The REST API compresses the response if the client properly specifies this header. The response includes the header Content-Encoding: gzip or Accept-Encoding: deflate. You can also compress any request by including a Content-Encoding: gzip or Content-Encoding: deflate header. Response Compression The REST API can optionally compress responses. Responses are compressed only if the client sends an Accept-Encoding header. The REST API is not required to compress the response even if you have specified Accept-Encoding, but it normally does. If the REST API compresses the response, it also specifies a Content-Encoding header. Request Compression Clients can also compress requests. The REST API decompresses any requests before processing. The client must send a Content-Encoding HTTP header in the request with the name of the appropriate compression algorithm. For more information, see: • Content-Encoding at: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11 • Accept-Encoding at: www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3 • Content Codings at: www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.5 3 Introducing Lightning Platform REST API Using Conditional Requests 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 4