Transcription
REST API Developer GuideVersion 42.0, Spring ’18@salesforcedocsLast updated: April 12, 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.
CONTENTSChapter 1: Introducing Lightning Platform REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Lightning Platform REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Using Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Using Conditional Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Using cURL in the REST Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Understanding Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Defining Connected Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Understanding OAuth Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Understanding the Web Server OAuth Authentication Flow . . . . . . . . . . . . . . . . . . . . . . 7Understanding the User-Agent OAuth Authentication Flow . . . . . . . . . . . . . . . . . . . . . . 12Understanding the Username-Password OAuth Authentication Flow . . . . . . . . . . . . . . . 15Understanding the OAuth Refresh Token Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Finding Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Use CORS to Access Salesforce Resources from Web Browsers . . . . . . . . . . . . . . . . . . . . . . 20Chapter 2: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Step One: Obtain a Salesforce Developer Edition OrganizationStep Two: Set Up Authorization . . . . . . . . . . . . . . . . . . . . . .Step Three: Send HTTP Requests with cURL . . . . . . . . . . . . . .Step Four: Walk Through the Sample Code . . . . . . . . . . . . . .Using Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222222252632Chapter 3: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Getting Information About My Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34List Available REST API Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34List Organization Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35List Available REST Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Get a List of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Get a List of Objects If Metadata Has Changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Working with Object Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Retrieve Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Get Field and Other Metadata for an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Get Object Metadata Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Working with Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Create a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Update a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Delete a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Get Field Values from a Standard Object Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
ContentsGet Field Values from an External Object Record by Using the Salesforce ID . . . . . . . . . . 46Get Field Values from an External Object Record by Using the External ID StandardField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Retrieve a Record Using an External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Insert or Update (Upsert) a Record Using an External ID . . . . . . . . . . . . . . . . . . . . . . . 47Traverse Relationships with Friendly URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Get Attachment Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Get a List of Deleted Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 56Get a List of Updated Records Within a Given Timeframe . . . . . . . . . . . . . . . . . . . . . . . 57Working with Searches and Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Execute a SOQL Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Execute a SOQL Query that Includes Deleted Items . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Get Feedback on Query Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Search for a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Get the Default Search Scope and Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Get Search Result Layouts for Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66View Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Insert or Update Blob Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Working with Recently Viewed Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75View Recently Viewed Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Mark Records as Recently Viewed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Managing User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Manage User Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Working with Approval Processes and Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Get a List of All Approval Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Submit a Record for Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Approve a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Reject a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Bulk Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Get a List of Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Get a Particular Process Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Trigger Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Using Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Describe Event Monitoring Using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Query Event Monitoring Data with REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Get Event Monitoring Content from a Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Download Large Event Log Files Using cURL with REST . . . . . . . . . . . . . . . . . . . . . . . . . 88Delete Event Monitoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Generate Hourly Event Log Files (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Using Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Execute Dependent Requests in a Single API Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Update an Account, Create a Contact, and Link Them with a Junction Object . . . . . . . . . 94Update a Record and Get Its Field Values in a Single Request . . . . . . . . . . . . . . . . . . . 96Create Nested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
ContentsCreate Multiple Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Chapter 4: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Resources by Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Describe Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107SObject Basic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107SObject Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108SObject Get Deleted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108SObject Get Updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110SObject Named Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111SObject Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112SObject Rows by External ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112SObject Blob Retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113SObject ApprovalLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114SObject CompactLayouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Describe Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120SObject PlatformAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122SObject Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123SObject Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124SObject Suggested Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125SObject User Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Platform Event Schema by Event Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Platform Event Schema by Schema ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129AppMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Compact Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Standard Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Custom Invocable Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141List View Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142List View Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Support Knowledge with REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Data Category Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Data Category Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Articles List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Articles Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Parameterized Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Process Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Process Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181QueryAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Quick Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
ContentsRecent List Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Recently Viewed Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Record Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Record Count Response Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Relevant Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Retrieve Knowledge Language Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Search Scope and Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Search Result Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Search Suggested Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Search Suggested Article Title Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Search Suggested Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Composite Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213SObject Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218SObject Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Assignment Rule Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Call Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Limit Info Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Package Version Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Query Options Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Status Codes and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
CHAPTER 1In this chapter . Lightning PlatformREST Resources Using Compression Using ConditionalRequests Using cURL in theREST Examples UnderstandingAuthentication Use CORS to AccessSalesforce Resourcesfrom Web BrowsersIntroducing Lightning Platform REST APIREST API provides a powerful, convenient, and simple Web services API for interacting with LightningPlatform. Its advantages include ease of integration and development, and it’s an excellent choice oftechnology for use with mobile applications and Web 2.0 projects. If you have many records to process,consider using Bulk API, which is based on REST principles and optimized for large sets of data.REST API uses the same underlying data model and standard objects as those in SOAP API. See the SOAPAPI Developer Guide for details. REST API also follows the same limits as SOAP API. See the Limits sectionin the SOAP API Developer Guide.To use the API requires basic familiarity with software development, web services, and the Salesforceuser interface.Use this introduction to understand: The key characteristics and architecture of REST API. This will help you understand how yourapplications can best use the Lightning Platform REST resources. 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 APILightning Platform REST ResourcesLightning Platform REST ResourcesA 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 objec
Apr 12, 2018 · API Developer Guide for details. REST API also follows the same limits as SOAP API. See the Limits section in the SOAP API Developer Guide. Using Conditional Requests Using cURL in the REST Examples To use the API requires basic familiarity with software development, web services, and the Salesforce user interface. Understanding
![API Ballot: [Ballot ID] – API 510 & API 570, Deferrals, Rev05](/img/5/api510andapi570deferralsrev5.jpg)
