Friday, November 5, 2010

Salesforce REST API Access Token

In my first article on the SFDC REST API I showed how you authenticate to Salesforce using OAuth. The main output of this process is the access token which must be provided when you make any other calls to the REST API. One of the first things I wondered about the access token is, how long does it last? It turns out that the access token is tied to the normal session timeout in SFDC and is configurable for each instance. To view or change the setting log into your account, click Setup, then under Administration Setup select Security Controls then Session Settings.
image
You can see that in this case the timeout is set to two hours. This means that if you go for more the two hours without calling the REST API the access token will expire. You can change this setting from between 15 minutes and 8 hours.
The next question is, when the access token expires does the user have to go through the login process again? Fortunately the answer is no, this is where the refresh token comes into play. When we did the initial authentication process to get the access token we also received a refresh token. The refresh token can be used to get a new access token without the user having to enter their username and password again.
The code to get a new access token is pretty much the same as the code we initially used to get access token.

{ 

string URI = "https://login.salesforce.com/services/oauth2/token";
StringBuilder body = new StringBuilder();


body.Append("refresh_token=" + refreshToken + "&");
body.Append("grant_type=refresh_token&");
body.Append("client_id=" + clientID + "&");
body.Append("client_secret=" + clientSecret + "&");
body.Append("redirect_uri=" + redirectURL); 

string result = HttpPost(URI, body.ToString()); 

JavaScriptSerializer ser = new JavaScriptSerializer();
token = ser.Deserialize<TokenResponse>(result); 

} 

You will notice two differences. First instead of passing the code we got when the user logged in, we pass the refresh token, and second we set the grant type to refreshToken instead of authorization_code. The function will return the same response as the initial call did with one exception. According to the OAuth specs the service is not required to return a new refresh token when a new access token is generated. This appears to be the case with SFDC since this call does not return a new refresh token. This means that you need to hold onto the original refresh token to use each time you request a new access token.

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.