API: Introduction
APIs (Application Program Interfaces) and web services are good, solid, geeky, fun. They are not exclusive to Salesforce and for the most part are conceptually easy to understand. A simple way to explain them is that APIs and web services engage in the asking, or giving, of data, between two parties. These are inbound or outbound transactions that are, in our context, sent into, or out of, Salesforce.
The concept is easy enough to understand. However, web services are not simple switches that you turn on and off. In reality, web services are made up of many elements that each must work together to get data seamlessly flowing from system to system. Ami Assayag and I recently led a webinar on the subject of APIs and web services, alongside Salesforce Developer Evangelist Josh Birk. As Ami and I prepared, we faced the challenge of staying on point, as there are a tremendous number of related topics of interest to explore.
Because of this, our team of Lab-Coders are kicking off a new series of Lab Coat Lessons, covering various aspects of using APIs and web services. But before we get too far, let’s start with some basics...
The Basics
API work can be broken down into two main architectures; REST and SOAP. With REST (Representational State Transfer), you’ll be working with “objects” - preparing them for requests and parsing them from responses. REST is also where you’ll find request verbs like GET, POST, PUT, and DELETE. These are similar to CRUD (Create, Read, Update, and Delete).
SOAP (Simple Object Access Protocol) tends to be less object or data driven, and is more logic and process oriented than REST. Arguably, one API architecture isn’t better than the other. However, one may be preferred as each has its own ideal use case. With Salesforce integrations, we use what exists, or needs to be used, on the remote system side. If there isn’t a prescribed API architecture in use, or client reason not to, we utilize REST.
There are also two data “formats” that are typically used. They are XML (Extensible Markup Language), and JSON (Javascript Object Notation). XML can be used like a format, but in itself is more of an entire language. Whether to use XML or JSON is another heavily debated topic in developer circles. We boil the decision down based on use case and personal preference.
Here are two examples of a similar request, one written in XML and a second in JSON. We encourage you to take a minute and visually try to spot the differences between the two:
XML
JSON
Observations
As you can see, the XML and the JSON are the same when it comes to getting the same data from point A to point B. In more complex scenarios, the JSON side will tend to be less cryptic and easily readable at a glance. For the purposes of this blog, understand that both XML and JSON can both be created and consumed by Apex code.
For a quick read on additional difference, check here.
Next Steps
In our next post, Mike Katulka, CRM Science Technical Lead, will share some functional code for making REST based callouts from Salesforce.
Future Post Topics:
Authentication
cURL for Watson
Deserialization Techniques
Callouts w/ Lightning Components
Other Useful Tools
Curious about something else? Let us know
Useful Links:
Some additional resources for you about various system classes available for your use in Apex are below.
We are a certified Salesforce Product Development Partner and have built outstanding applications for a number of industries. Contact us about your next project or Salesforce application.
