By: Urmila Pawar
Why do we need to build an API in Salesforce?
We customize and automate the functionality within Salesforce. But what if the external system wants to communicate with Salesforce and utilize these functionalities? In order to solve this barrier we create API, so that the external systems can read data from Salesforce, or write data to Salesforce.
API Basics
An API is a way to communicate with a component without bothering with its internal functionality. An API usually expects input in a specific format, and responds in a specific format as well.
SOAP vs REST API
| SOAP | REST API |
| SOAP stands for Simple Object Access Protocol | REST stands for Representational States Transfer |
| SOAP is a protocol | REST is an architectural pattern |
| SOAP uses service interfaces to expose its functionality to client applications | REST uses Uniform Service locators to access the components on the hardware device |
| SOAP needs more bandwidth for its usage | REST works with lower bandwidth |
| SOAP only works with XML formats | REST works with plain text, XML, HTML, and JSON |
| SOAP cannot make use of REST | REST can make use of SOAP |
Creating Connected App in Salesforce
You can follow the Salesforce Trailhead links to create a connected app. https://trailhead.salesforce.com/en/content/learn/projects/build-a-connected-app-for-api-integration/create-a-connected-app
REST API Communication Flow
REST Annotation
We can expose your Apex class and methods so that external applications can access your code and your application through the REST architecture.
- We use @RestResource annotation to expose it as a REST resource
- We can add the @HttpDelete annotation to your method to expose it as a REST resource that can be called by an HTTP DELETE request
- We can add the @HttpGet annotation to your method to expose it as a REST resource that can be called by an HTTP GET request
- We can add the @HttpPost annotation to your method to expose it as a REST resource that can be called by an HTTP POST request
- We can use the System.RestRequest class to access and pass request data in a RESTful Apex method.
- Represents an object used to pass data from an Apex RESTful Web service method to an HTTP response.
@RestResource(urlMapping=’/CustomAPI/*’)
global with sharing class CustomResource {
@HttpDelete
global static void doDelete() {
//some delete operation here
}
@HttpGet
global static CustomInfo doGet() {
//some query operation here
//return queried information
}
@HttpPost
global static String doPost(String name,
//some dml operation here
//return the ID of recently created record
}
}
Example
@RestResource(urlMapping=’/OrderProcessor/*’)
global with sharing class OrderProcessingResource {
@HttpGet
global static CustomInfo doGet() {
RestRequest request = RestContext.request;
RestResponse response = RestContext.response;
String ordertId = req.requestURI.substring(req.requestURI.lastIndexOf(‘/’)+1);
Order orderWithLineItems = [SELECT Id, (SELECT Id, Name FROM OrderLineItems)
FROM Order
WHERE Id = :ordertId];
return orderWithLineItems;
}
}
Calling API from External System
1. Authentication Request
Salesforce token request endpoint
Production : https://login.salesforce.com/services/oauth2/token
Sandbox : https://test.salesforce.com/services/oauth2/token
We are using Username Password Flow for Authentication.
Following request fields are required:
- grant_type : Must be password for this authentication flow.
- client_id : The Consumer Key from the connected app definition.
- client_secret : The Consumer Secret from the connected app definition. Required unless the Require Secret for Web Server Flow setting is not enabled in the connected app definition.
- username : End-user’s username.
- password : End-user’s password. You must append the user’s security token to their password
Sample URL :
https://test.salesforce.com/services/oauth2/token?grant_type=password&client_id=xxxxxxxxxxxxxxxxxxxxxx&client_secret= xxxxxxxxxxxxxxxxxxx&username= user@test.com.sandbox&password=password+securitytoken
Sample Response :
{
“access_token”: “xxxxxxxxxxxxxxxxxxxxxxxx”,
“instance_url”: “https://sandbox.cs70.my.salesforce.com”,
“id”: “https://test.salesforce.com/id/00Dxxxxxxxxxxxx/005xxxxxxxxxxxx”,
“token_type”: “Bearer”,
“issued_at”: “1549347983877”,
“signature”: “xxxxxxxxxxxxxxx=”
}
2. GET Order Request
From the response received as part of the authentication request please note the “access_token” and “instance_url”. These will be required for further request.
Method Type : GET
URL : instance_url+’/services/apexrest/OrderProcessor/’+orderId
For Example : https://cs27.salesforce.com/services/apexrest/OrderProcessor/801xxxxxxxxxxxxxxx
Parameters :
| content-type | application/xml |
| authorization | Bearer access_token |
Sample Response:
{
“Order”: {
“Id”: “801xxxxxxxxxxxxxxx”,
“OrderLineItems”: [{
“Id”: “802xxxxxxxxxxxxxxx”
}]
}
}