Monday, November 1, 2010

Salesforce REST API Part 2

In my last post I introduced the new Salesforce REST API. Now I will dig into some of the details of how to use the interface.

URIs

Like any REST API you access resources in Salesforce using various URIs like this:
http://na1.salesforce.com/services/data/v20.0/sobjects/Account/
The first part of the URI "http://na1.salesforce.com/" identifies your Salesforce instance. This is needed because different accounts will be hosted on different servers. As I showed in the last article you retrieve the instance URL during the authentication process.
The next piece "/services/data" identifies the service and is the same for all REST API calls. The following piece "v20.0/" is the version number which specifies the version of the API you want to use. You can retrieve a list of the available versions by calling the List Versions command which I will show in a minute. The Version command will return a URL that contains both the service and version parts of the URI.
Next 'sobjects' is the resource you will be calling. You can get a list of the available resources using the List Resources command.
Finally anything after the resource is specific to the resource and command you are calling.

Return Type

By default the REST API returns its results in JSON format. You can also request that the results be returned in XML. To do this just append .xml to the end of the URI you are calling. The documentation also indicates that you can do this using the HTTP ACCEPT header, but I have not been able to get that to work. I my examples I will be showing the results in XML.

List Versions Command

The list versions command looks like this:
https://na5.salesforce.com/services/data/.xml
Note that in all my examples I will be using the instance URL of my account, be sure to substitute your own.
Here is what is returned:
<?xml version="1.0" encoding="UTF-8"?>
<Versions>
<Version>
<label>Winter &apos;11</label>
<url>/services/data/v20.0</url>
<version>20.0</version>
</Version>
</Versions>


In this case there is only one version available, version 2.0. Also returned is the label for the version "Winter '11" and the URL to access the API for this version. One thing to note about this command is that you do not need to authenticate before calling it. It works whether you pass the access token or not.


List Resources Command

The next command you will want to know about lists the resources available for a specific version. The command looks like this:

http://na1.salesforce.com/services/data/v20.0/.xml

Remember if you want to return the results in JSON format just leave off the .xml or specify .json instead of .xml.

The result looks like this:


<?xml version="1.0" encoding="UTF-8"?>
<urls>
<sobjects>/services/data/v20.0/sobjects</sobjects>
<search>/services/data/v20.0/search</search>
<query>/services/data/v20.0/query</query>
<recent>/services/data/v20.0/recent</recent>
</urls>


This shows the resources that are accessible through the API. The current resources are:

sobjects – Allows you to access information about the objects in the database and to insert, read, updated and delete objects.

query – Allows you to run SOQL queries.

search – Allows you to run a SOSL search.

recent – This seems to return a list of recent objects, but I haven't found any official documentation on it.

That's all for now. In future postings I will get into some more details on how each of these resources is used.

3 comments:

Spoonmore said...

To output xml

System.Net.HttpWebRequest req = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(URI + "/query?q=SELECT+name+from+User+Limit+10");

req.Method = "GET";
req.Headers.Add("Authorization: OAuth " + subsribeId);

req.Accept = "application/xml";
System.Net.WebResponse resp = req.GetResponse();

works great

Spoonmore said...

Thanks for the great info

Thomas Gagne said...

Good stuff. I'm working on a command-line tool for SOQL using curl. With an XML response I'm hoping to pipe it through xsltproc to format the output into a more ordinary CSV-like response.

Perhaps it's not necessary, and I should look for other command-line tools, but it's not a worthless exercise, either.