Saturday, January 8, 2011

Salesforce REST API Record Creation

In my last few articles I showed the basics of how to connect to Salesforce using the REST API and how to use some basic functions. Now lets look at how to actually manipulate the data stored in SFDC. We will start by looking at how to insert a new record.
When you are working with tables (called objects in the SFDC nomenclature), the URI will look something like this:
http://na1.salesforce.com/services/data/v20.0/sobjects/Account/

  • http://na1.salesforce.com  is the instance URL that you get during the login process.
  • /services/data/v20.0/ indicates the version of SFDC you will be using.
  • sobjects/ is the resource we will be accessing, in this case the SFDC objects (tables).
  • Account/ is the name of the object we will be creating the new record in.
To insert a new record we will do an HTTP POST to this URI. In the headers we will pass the authorization token, and in the body we will pass the JSON encoded data we want to insert. For example here is a simple piece of JSON that will insert a new Account with the name TestAccount and number 1234567.
{    
"Name" : "TestAccount",
"AccountNumber" : "1234567"
}

Now lets look at the C# code to perform this insert. First, to simplify the creation of our JSON lets create an Account class that we can serialize.

public class sfdcAccount
{
public string Name { get; set; }
public string AccountNumber { get; set; }

}

Next we will setup our URI and the account object

var uri = instanceURL + "/services/data/v20.0/sobjects/Account/";

var acct = new sfdcAccount();
acct.Name = "NewAccount";
acct.AccountNumber = "123456";

and then serialize the account object into JSON.

var ser = new JavaScriptSerializer();
var body = ser.Serialize(acct);

We can now create our HTTP request.

var req = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(uri);
req.Headers.Add("Authorization: OAuth " + accessToken);
req.ContentType = "application/json";
req.Method = "POST";


Here we create an HttpWebRequest object pointing to the URI we specified earlier. We then set a header that contains the access token we got during the login process, set the content type to JSON and finally specify that this is an HTTP POST request.

Next we need to add the body of the request. This code will convert our JSON to a byte array an attach it to the request.

byte[] data = System.Text.Encoding.ASCII.GetBytes(body);
req.ContentLength = body.Length;
var os = req.GetRequestStream();
os.Write(data, 0, data.Length);
os.Close();

Finally we execute the request and retrieve the result that SFDC sends back.

WebResponse resp;

try
{
resp = req.GetResponse();
}
catch (WebException ex)
{
resp = ex.Response;
}

if (resp == null) return null;
System.IO.StreamReader sr = new System.IO.StreamReader(resp.GetResponseStream());
return sr.ReadToEnd().Trim();

The try/catch around the request is important. When there is an error executing the command SFDC will return a HTTP response code of 400 which will throw an exception. To resolve this problem we catch the exception and retrieve the response object from the exception.

Assuming there are no errors, SFDC will return a JSON response that looks like this

{
"id":"0017000000hX4BIAA0",
"errors":[],
"success":true
}

First we get back the internal id of the record that was created. We can use this later to read, update, or delete this record. We also get back a true/false field indicating the success or failure of the insert and an errors field. I have not yet found a case where these are used since an error will return a different response. For example if we make the AccountNumber greater the 40 characters we will get the following response:

{
"fields":["AccountNumber"],
"message":"Account Number: data value too large: 1234567890123456789012345678901234567890123456789012345678901 (max length=40)",
"errorCode":"STRING_TOO_LONG"
}

5 comments:

Timo said...

Great article. Thanks that you sharing us this.

Shailesh said...
This comment has been removed by the author.
Shailesh said...

Thanks for article!!
I've a question here;

I've created my own class with methods which creates Leads and contacts in Salesforce account.

How can we pass json string as a request instead of sending parameters in query string to @httpPost using C#?
Can we use @HttpPost to perform insert and update operation in one go?

Dan Boris said...

@Shailesh: I am not sure what your question is? The JSON is not passed as a query string, it IS passed as part of the request.

Icaro Sites said...

Tks! Very helpfull article!

Can u update it or create a new version using HttpClient instead HttpWebRequest ?!

Im trying to use HttpClient, but its not working to POST and PUT, just with GET methods.

I always receive a message: "Can not desrialize SObject out of VALUE_STRING token. errorCode: JSON_PARSE_ERROR";

Im using the same json at WebRequest and HttpClient. With WebRequest, following your example, it works well..

Here is my code with HttpClient:

var uri = "https://na15.salesforce.com/services/data/v27.0/sobjects/Account";

var acc = new Account();
acc.Name = "RestAPIHttpClient";

var ser = new JavaScriptSerializer();
var body = ser.Serialize(acc);

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("Authorization", "Bearer " + binding.SessionHeaderValue.sessionId);

var response = await client.PostAsJsonAsync(uri, body);
var stringresponse = await response.Content.ReadAsStringAsync();
Console.WriteLine(stringresponse);

Many tks in advance!