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.

  1. We use @RestResource annotation to expose it as a REST resource
  2. 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
  3. 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
  4. 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
  5. We can use the System.RestRequest class to access and pass request data in a RESTful Apex method.
  6. 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:

  1. grant_type : Must be password for this authentication flow.
  2. client_id : The Consumer Key from the connected app definition.
  3. 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.
  4. username : End-user’s username.
  5. 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”

                       }]

                }

}