There are different APIs which developers can use to integrate with Salesforce org. In this blog post, we will talk about what APIs we have and when to use them.

What are Salesforce APIs and how developers can use them?

We have about 8 APIs till now. While all these serve a similar purpose of accessing data from Force.com platform or Database.com but there are key differences between each of these APIs.The important point to remember is that all of these APIs operate identically across Force.com platform and Database.com

SOAP API:
The most well-known API is the SOAP API. As the name indicates, it uses SOAP as a wrapper for API operations. Most of the API traffic is from SOAP API because its been in the market for long time.

SOAP API is around for long time:
SOAP APIs is considered as the “granddaddy” of the APIs. SOAP API is used in enterprise setting because tooling is used to create SOAP messages. You can even build a SOAP envelope by concatenating strings but that task is pretty laborious. So we use tools like Visual Studio or Eclipse to import the WSDL. Salesforce also offers a Java toolkit called WSC through which you can import a .jar file and it provides you a nice programming interface to create records, run queries etc.

Metadata API:
The second type of API is Metadata API. The SOAP API is focussed towards accessing data and manipulating records, whereas the Metadata API focusses on Metadata. This API is uses to manipulate layouts, visualforce pages, apex triggers and classes- pretty much everything that you can do from the browser interface.

Metadata API is not just used to fetch. Tools like Force.com IDE use Metadata API to make changes to your Salesforce org. So to summarize, Metadata API is not just for querying information but it is also used for updating or creating objects.
Metadata API is also a SOAP based API so you will need a library on the client side or you can use the tools to import the WSDL.

Apex API:
The metadata API enables you to upload APEX classes, but tools like Force.com IDE needs more functionality. Apex API exposes API objects and calls which allow you to execute an anonymous block of code, run tests and compile classes. Most developers won’t ever need to use APEX API directly but they all are benefited from its use in the force.com IDE.
This is also a SOAP API so you have to download the WSDL to get started.

APEX SOAP:
This is a third API. APEX SOAP Api enables you to expose APEX methods via SOAP. For example, you have an Apex method which takes parameters like person name, company name and phone number and then it creates an Account and Contact in one operation.You can expose this method as a service operation by using @WebService annotation above the method.

But one of the drawbacks of SOAP is that it’s pretty heavyweight.

REST : If you just need a point-to-point call, then SOAP can be overkill. In SOAP, you will need an envelop and headers and a whole spec which contains information on how to process the message. But if your requirement is just to send a message from a client to a server and send back the response, you can use something simple which is REST.

REST is Representational State Transfer and it is very simple as compared to SOAP. The main idea behind REST is that every object in the system is associated with a URL. When you perform operations on that URL, you are accessing a representation of the state of that object. For example, if you do a GET on a URL representing an account record, you will get back XML or JSON response with the state of that account. You can perform a POST request to create a new account, DELETE request to delete an account.

They have a new addition to the HTTP methods known as PATCH, this can be used to update the account. In nutshell, we are passing XML or JSON back and forth and leveraging HTTP operations. REST makes it easy for programmers.

SOAP messages are formatted as XML. JSON stands for JavaScript Object Notation is more concise data representation than XML. In JSON, data is represented in form of object. You have property names, property values and you can also have nested objects and arrays.

For instance, if you use REST API to do a query which would be a GET request on a URL which ends in “query?q=soql query”, you will recieve an array of records formatted in JSON.

The main thing about JSON is that its comparatively more concise and lightweight. Since there is less data on the wire so it is faster also. But from programmer point of view, if you are working in JavaScript or PHP or Java or any other language, there are great high-performance libraries available for parsing JSON. Its easy to work with and you don’t have to download a WSDL particular to the Salesforce API.

The great thing about using URLs is when you have a foreign key relationship. For instance, if you have an account and contact, if you just retrieve the contact, it will contain the URL to retrieve the account as well. Then you only need to perform GET operation on that URL to retrieve the account.

REST API:
For REST, the developer doesn’t need to know what objects are available to query. The REST API is been around since Spring ’11 release and it also encompass metadata operations. But in REST API, the metadata is read-only. A programmer can perform a similar operation using REST, you could retrieve a list of objects which are available in the system. For a particular object, you can also retrieve the list of its fields. You can build dynamic interfaces using REST API.

Usually, REST API operates on small number of records. You can retrieve a single record using GET request or you can also run a query to get back a set of records.

Bulk API:
Bulk API has been around longer than REST API. It is an asynchronous API, and it has the ability to work with large data sets like 600,000 records. But you should not use this API if you just need a handful of records and also if you want to create a dynamic UI. Bulk API is a special purpose API to load large amount of data.

With the Bulk API, the programmer/developer must know about the object in their salesforce org because if you are using BUlk API to load data, you have to formate the data based
on the schema.

Apex REST:
Just like in Apex SOAP, you can write an Apex method and expose it via a SOAP interface. Similarly, we can have an APEx method exposed via REST. That’s extremely helpful because one of the properties of REST API is that you can do updates and they are on individual records. For instance, if you want to do an atomic update in which you want to update the account and a contact record and you also want them either both to succeed or both to fail. Its not possible to do that via REST API. In this case you have to do a PATCH on the account and a PATCH on the contact.

So basically, you can’t have a transaction.Scenarios like this when you have an Apex method that performed both of those updates and expose the method via REST, you will call the method, send the account and contact info, and then make the updates in that method. The way Apex methods work is that if in a method you have one successful operation and the next operation fails in an error, then your method will roll back any change that were made.

To summarize, you can have an Apex method that perform multiple operations and it is effectively one transaction. This is really helpful when you want to work with more complex data.

Streaming API:
The next API is the Streaming API. The APIs that we have discussed so far, enables you to make a call and get back data or update data, whereas the Streaming API is used to create a push topic based on a query and it get updates regularly based on the results of that query change. So you can pick “select name from some object” and then subscribe to the topic channel. When there are no changes, you get nothing.Your app sits there and waits. But as soon as somonene creates or update a record which matches your push topic query, you will receive a notification which contains fields thats are in the SELECT statement of the topic query. The notification of data change is also pushed to the client.

You can design your SOQL query to match whatever constraints you like even you can narrow down to changes on an individual record. This tool enables you to build dynamic user interfaces.

Chatter API:
The API that we have discussed so far are usually for general purpose. Those API can be used on any object in the database. You can use all those APIs to communicate with Chatter if you are aware of the underlying chatter model.But to access chatter that way is very laborious because as a developer you have to thread those objects together urself. And it is also very costly in terms of round trips. You have to make several trips using REST API or SOAP API to assemble the data which you want to show to the user.

In this case, Chatter API comes to rescue. It gives a higher-level of abstraction of that data. Instead of dealing with the underlying objects, you will deal with slightly abstract representaion of a user’s chatter feed. It is designed so that, you can make one call and retrieve pretty much everything you need. In some cases, you might have to drill down little bit but in most applications which are manipulating chatter are making standard requests.

Course:
I have a course on API with examples, please check the complete course here:

Resources :
Easier Developer Doc and Salesforce Searches on Chrome