Salesforce REST API Integration
Getting started with the Salesforce developer ecosystem
Being in the Software as a Service space, you have to admire what Salesforce has managed to accomplish. It would be hard to argue their success, particularly at the enterprise customer level.
While they have one of the most tuned and well-known sales approaches in software, there is almost a feeling that when a company gets to a certain size, they just decide it’s time to use Salesforce online training. It’s due to this that if you have a product that operates in the Sales and Marketing space, there is huge opportunity in tapping into the Salesforce community and ecosystem.
For example, we’ve built the Salesforce integration to capture the on-site behaviour of leads when they’re browsing your website (E.g. when a lead views your pricing page or watches a webinar), and send this directly into Salesforce ready for your sales team to act on within their existing workflow.
Digging into the Salesforce developer ecosystem
With a company that has the breadth and depth of product that Salesforce offers, there will always be pros and cons to getting your head around their documentation and terminology.
They have an incredible developer community, including their own Stack-overflow-esque forums. If you hit a road block, it’s likely someone’s hit it before you and you can find a documented solution.
Similarly they have an extremely robust e-learning platform with tracks that you can complete across a plethora of different subjects to get up to speed on a lot of their terminology and principals.
There can, however, be an abundance of content to sift through and it can be an incredibly time consuming process particularly if building and developing on the Salesforce Platform is not going to be the core responsibility of your job!
This blog post is really focused around communicating, at a very basic level, the key concepts needed to build a basic Salesforce REST API integration.
Salesforce API Integration vs Salesforce App
It’s important to highlight the difference between a Salesforce API Integration and a Salesforce App that you’d find on their AppExchange (essentially the Salesforce App Store.)
Listing an app within the Salesforce AppExchange will give you the ability to build your product directly into the Salesforce platform. For example, visualizing your product’s data directly within a component in Salesforce. While there are clear benefits in having a presence within this ecosystem it’s important to note that there are some costs associated with doing so.
A Rest API integration is a lot simpler and is primarily focused around sending data from your application and fetching data from Salesforce. Currently there is no cost associated with this type of integration however it’s worth noting that REST integrations are only accessible to Salesforce users on their enterprise plans (there is scope to get REST API access on Professional and Group editions but involves getting your app whitelisted.)
For the purposes of this post, our example REST API integration is going to be super basic. Our app is going to have customer data that we want to send to Salesforce and there will be customer data in Salesforce that we want to retrieve.
Essentially then, our REST API integration is going to need to do 3 critical things:
- Allow a user of our application to authoress us to access and transfer their Salesforce data on their behalf.
- Allow a user to push data from our application to Salesforce.
- Allow a user to retrieve Salesforce data to be used within our app.
Getting set up with Salesforce
Create a free developer account
Start by getting yourself a free Salesforce online training in Hyderabad Developer account
The Salesforce developer accounts are awesome and pretty much give you a working Salesforce organisation (an organisation is Salesforce’s terminology for an account) so you can get a feel for the interface and even add and manage users.
Set up a Connected App
Once you have your developer account set up you’ll want to set up a Connected App. Connected Apps have the ability to offer a lot of functionality and sometimes that can make it a bit difficult to get your head around them.
For the purposes of this and how we’re going to use it, it’s easiest to think of a connected app as a small app that sits on Salesforce’s infrastructure that you point your integration to. It is responsible for managing the authentication and also the routing of requests to the relevant client instances.
Once you’ve set up your Salesforce developer account, you can set up a connected app by clicking the Setup icon in the top-right navigation menu and select Setup.
Enter App Manager in the Quick Find box and then select App Manager.
Under Selected OAuth Scopes:
- Select Access and manage your data (API).
- Click Add.
Once you’ve set up your app, you’ll be given a Consumer Key and a Consumer Secret for you app.
The basic Salesforce Oauth data flow
With the connected app set up, its handy to get an idea of how the data flow works.
To start, your user is directed to a Saleforce.com authorization endpoint, there they log in and approve access for your app to access their data.
After a successful authorization Salesforce training sends a response with an Access token and Refresh token.
The Access token is to be passed in the header of all API requests for data. This token has an expiry date and will always expire. By default the Connected Apps have an access token with an expiry of 15 minutes (inline with the sessions settings within your Salesforce settings).
The Refresh token is to be used to retrieve a valid access token (e.g. when the current access token expires). You can change the expiry settings on this but you can also set this never to expire, only when it revoked.
Example API calls:
To make the initial authorization request for a user to grant your app access to their data (this is where your user is initially directed to a Saleforce.com authorization endpoint and logs in) you’d make the following request. The client_id in the below call will be your consumer ID from the connected app. The redirect_uri will be the Callback URL.
curl https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=YOURCONSUMERID&redirect_uri=https://www.yourappname.com/api/callback
A successful response from this will redirect the page to a Salesforce login page where the user is able to login and authenticate. After Salesforce confirms that the client has authorised your app to access their data, the end-user’s browser is redirected to the callback URL you’ve specified by the redirect_uri parameter. Salesforce then appends an authorisation code to the redirect URL, their request will look similar to the below.
I actually prefer to use a combination a contacts ‘describe’ endpoint, which will return all of the fields we can populate about our user.
Example request:
curl https://INSTANCE.salesforce.com/services/data/v20.0/sobjects/Contact/describe -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
That will give a detailed response of all of the fields available. (I’ve just given an example of the ‘first name’ element for brevity)
{ "autoNumber": false, "byteLength": 120, "calculated": false, "calculatedFormula": null, "caseSensitive": false, "controllerName": null, "createable": true, "custom": false, "defaultValue": null, "defaultValueFormula": null, "defaultedOnCreate": false, "dependentPicklist": false, "deprecatedAndHidden": false, "digits": 0, "externalId": false, "filterable": true, "groupable": true, "htmlFormatted": false, "idLookup": false, "inlineHelpText": null, "label": "First Name", "length": 40, "name": "FirstName", "nameField": false, "namePointing": false, "nillable": true, "picklistValues": [], "precision": 0, "referenceTo": [], "relationshipName": null, "relationshipOrder": null, "restrictedPicklist": false, "scale": 0, "soapType": "xsd:string", "sortable": true, "type": "string", "unique": false, "updateable": true, "writeRequiresMasterRead": false }Once you’ve got the fields you can then use them (or a selection) to build a custom query:
curl https://INstance.salesforce.com/services/data/v42.0/query/?q=SELECT+id,name,email,phone+from+Contact -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
That will return all contacts with their associated properties.
{"totalSize":1,"done":true,"records":[{"attributes":{"type":"Contact","url":"/services/data/v42.0/sobjects/Contact/id"},"Id":"id","Name":"Jonny Appleseed","Email":"[email protected]","Phone":"555-555-555"} ]}That should now give you a way to retrieve contact data from Salesforce to use within your app.
Further resources
Hopefully that gives a good enough foundation to start exploring more of the Salesforce cpq training objects you can interact with through a REST API integration. Here are some additional resources to more in-depth information about the Salesforce REST endpoints.