How To Develop Custom Salesforce SOAP API Endpoint

Custom SOAP API Endpoints could be a very powerful capability to enhance Salesforce Integration offering to the external applications. In custom APIs, we can make full use of all available programming capabilities of Apex, SOQL, and other programming artifacts.

In this article, we will discuss detailed steps on how to develop Custom SOAP APIs for Salesforce and how can we consume the SOAP API Endpoint using Postman API Client. We will also look for Service Operations return collection of records as part of Response.

Analyzing Salesforce Data Source

Step 1

We have a Custom Object “Invoices__c” that is holding the data for Customer Invoices. In this demo, we will develop a Custom SOAP API Endpoint to retrieve data from this custom object.

Code Development: Custom SOAP API Endpoint

Operation 1 - Returns a Collection 

Launch Visual Studio Code and Create New Salesforce Project.

Step 2

Once the project is added successfully, right-click the project and add a new Apex Class to the project.

Step 3

Name the new Apex Class “InvoiceService.cls”

Step 4

This will be a “global” class and this global class will be acting as a SOAP API Endpoint later on.

Step 5

In the class, we will define a new operation “getInvoicesByAmount” which takes a parameter “invoiceAmount” of type “integer”.

Step 6

This operation will define a variable of list type that returns the collection of invoices matching the criteria specified in the SOQL statement. This SOQL statement will query all invoices where the Invoice Amount is greater than the Input Amount Value.

This is business logic and could be defined as it fits the best to our business needs. And the beauty of a custom solution lies in the fact that we can handle any complex business requirements within the Service definition without exposing the complexities to the external applications.

Step 7

This operation will return the list of all invoices matching the criteria defined in the SOQL Query.

A Word of Caution

All the logic running inside API Endpoints is by default executing under System Context (highest privileges), so it is the responsibility of the API developers to make sure proper security restrictions are implemented as required.

Step 8

Now is the time to deploy the SOAP Endpoint to Salesforce Org. Right-click the project, select the “Deploy Source to Org” option to deploy the endpoint to the Org.

Invoke Custom SOAP API Endpoint using Postman

Launch Postman and start with a new API Request.

The Request Object

Step 9

Select “POST” as the request type.

Step 10

Specify the Service Endpoint using the following convention,

“<Salesforce Instance>/services/Soap/class/<SOAP API Endpoint Global Class Name>”

And for this demo, the complete SOAP Endpoint URI would be:

https://bansalp-dev-ed.my.salesforce.com/services/Soap/class/InvoiceService

Step 11

Select body section.

Step 12

Select request payload format as “raw”

Step 13

Select body content type as “XML”, since the request body is in XML format.

Step 14

Specify Session-Id within the Session Header. We can get this Session-Id from the Login Request.

Step 15

We will specify the SOAP Envelope Body for the SOAP API Endpoint as per the following conventions,

“<SOAP API Endpoint Operation Name>
    <Input Parameter Name>[Parameter Value]</ Input Parameter Name>
</ SOAP API Endpoint Operation Name >”

For this demo the SOAP Body would look like as follows,

“<getInvoicesByAmount>
    <invoiceAmount>1000</invoiceAmount>
</getInvoicesByAmount>”

Where the value of parameter “invoiceAmount” is “1000”, which means the SOAP Endpoint will return a list of Invoices for which “Invoice Amount is Greater Than 1000”.

Step 16

Click on “Headers” Tab to add the required headers to the SOAP Request.

Step 17

We have to add the following "Request Headers" to the request:

• “Content-Type” - It will define that the request body will be in XML format.
• “SOAPAction” - It will define the intent of the request. It is mandatory to include this header in the SOAP POST Request even if the value empty.

Step 18

Click on the “Send” button to submit the HTTP request.

The Response Object

Step 19

Now it is time to analyze the Response Object returned by SOAP API Endpoint as a result of the request we made.

a- Shows the number of result nodes returned based on the request. We can see there are 2 results or 2 Invoices returned where the Invoice Amount is greater than 1000.

b- Shows the Amount filter is working as expected and only those invoices are returned where the amount is greater than 1000.

Round 2: Change Amount Filter

The Request Object

Step 20

Now changing the parameter value to 500, which mean we are requesting all the invoices where the Invoice Amount is greater than 500.

Step 21

Click on the “Send” button to submit the HTTP request with the updated request body.

The Response Object

Step 22

Now it is time to analyze the Response Object returned by SOAP API Endpoint as a result of the request we made after updating the request body.

This time we can see 3 invoices coming in as part of the response object and if we notice the amount value, we will find only those invoices are returned where amount value is greater than 500.

This article is in continuation of my earlier one How to Develop Custom Salesforce SOAP API Endpoint – I

In this article, we will look for the Service Operations which return records by Indexers (Unique Ids) as part of Response.

Operation 2: Returns a Single Record By Indexer

As we can see the “getInvoicesByAmount” is bound to return a collection of all the matching records meeting the filter criteria, now we add another method to the Service Class which always returns a single record based on the filter criteria.

Such operations are always helpful to handle scenarios like “Get Something By ID, Get Something By Key”, to pinpoint the specific set of information.

For example in the upcoming demo, we will develop an operation that will be able to return the Invoice Information based on Invoice Number. In real-life scenarios, it is a very common implementation that every endpoint should implement one way or the other.

Lets’ go back to the “InvoiceService” class in Visual Studio Code-

Step 23

Add another operation “getInvoiceByNumber” which takes an input parameter “invoiceNumber” representing a unique identifier for Invoices

Step 24

We have a variable of type “Invoice__c” that will hold the invoice information returned by the filtered SOQL query. Consumer Applications will pass on this filter value while invoking this endpoint

Step 25

This information will be returned to the consumer applications as part of the response

That is it for the code. Now deploy the updated version of the service as we did in Step-8 in Article 1 of this series

Invoke Custom SOAP API Endpoint using Postman

Launch Postman and start with a new API Request.

The Request Object

Step 26

Since we have a new operation in place so we need to update the SOAP Envelope to point to the right operation of choice. Here is the new SOAP envelope for the new operation:

“<getInvoicesByNumber>
<invoiceNumber>INV-000000006</invoiceNumber>
</getInvoicesByNumber>”

This envelope uses the same convention as explained in Step-15

Here we are passing “INV-000000006” as the value to “invoiceNumber” parameter, which means we want to retrieve the information of the Invoice with the matching invoice number

Step 27

Click on the “Send” button to submit the HTTP request with the updated request body

The Response Object

Step 28

Now it is time to analyze the Response Object returned by SOAP API Endpoint as a result of the request we made after updating the request body.

This time we will see exactly 1 invoice coming in as part of the response matching the filter criteria as mention in our request body.

Salesforce SOAP API Endpoint Limitations

You can have multiple operations in the Service class but consumer applications can only request data using “One Operations at a Time”, which means the request body cannot have the call to multiple operations within the same request.

So lets’ modify the body request and try to include both operations together in a single request-

Step 29

Include both the operations to the request body

Step 30

Click “Send” to submit the request

Step 31

Now if we analyze the Respond Object, we would see an error coming up as the response body, explaining that “Only one operation within the same request is allowed”

So it is important to plan your SOAP API-based solution with consideration to this known limitation.

Security

All the logic running inside API Endpoints is by default executing under System Context (highest privileges), so it is the responsibility of the API developers to make sure proper security restrictions are implemented as required.

API Limits

It is also worth pointing to understand and plan the enterprise solution based on the API Limits offered by Salesforce Org. Here is the Salesforce Cheat Sheet for understanding API Limits. It is recommended to plan your solutions in line with permissible API Limits for your Salesforce Org.

Hope you enjoyed this article. Please leave your comments to let me know how you do like the content and how you do find it helpful to learn the topic.

Conclusion

Custom API Endpoints empowers to respond to compelling business needs efficiently. It allows us to deal with requirements involving complex business logic without exposing the complexities to consumer applications.

Hope you enjoyed this article. Please leave your comments to let me know how you do like the content and how you do find it helpful to learn the topic.