With the Salesforce hackathon fast approaching, I wanted to give a quick overview on building apps that use the force.com APIs (part of the Salesforce1 platform).

The force APIs are rich and varied, so sometimes just getting started can seem a little daunting.

What services are provided?

The force.com APIs give your application access to the authentication, data storage, and business rule services provided by the Salesforce1 platform. Some of the things you can do with the APIs include:

• Authenticate users based on a Salesforce username and password
• Query any data stored in a Salesforce account. Data access rules for the authenticated user are automatically applied.
• Create or update records in a Salesforce account. Data access rules for the authenticated user are automatically applied.
• Perform a free text search across all records in an account.
• Store and retrieve your own application-specific data in the Salesforce account.

This list covers the "core" force.com APIs. There are additional APIs for other services, and higher level access tools including Apex and Visualforce which are beyond our scope here.

Web application patterns

The Salesforce1 platform supports two primary architectures for building integrated web applications:

1. Salesforce1 "native" applications using Apex and Visualforce, or Javascript + HTML.
2. Connected applications which integrate via the SOAP or REST API

In the first case, you write your application code in the Apex language and use the Visualforce framework to build your web pages. You don't run any web or application servers yourself - all your code runs in the force.com environment. You can also implement single-page apps using AngularJS, Ember or something similar where your Javascript is served by force.com.

In the second case, you write your application code in any language you choose, and deploy your code to your own web and application servers (or deploy to a cloud host like Heroku). Your application integrates with force.com by making HTTP calls on the SOAP or REST APIs. This pattern is more flexible, but leaves you with more choices to make and more work to do.

Mobile application patterns

Because mobile apps introduce their own native-client environments, the choices for building mobile apps on Salesforce1 are a little more varied.

1. Build a hybrid app extension to the Salesforce1 app. Using Javascript and HTML, you can build new mobile pages which appear inside the Salesforce1 native app available for iOS and Android. User authentication comes for free since the user has authenticated into the Salesforce1 app. This corresponds most closely with our web pattern number 1 above. The result is: HTML+Javascript front-end, force.com back-end.

2. Build a native mobile app on iOS or Android, and use the force.com APIs directly in the mobile client by using the Salesforce iOS or Android SDKs. Users are authenticated with individual force.com logins. This is: native front-end, force.com back-end.

3. Build a native or hybrid mobile app which talks to a web application that itself uses the force.com APIs. All use of the force APIs is done server-side, and your client just talks to your custom API. Typically user accounts are stored in your application, and you use a single "API user" to access force.com. This corresponds to our web pattern number 2 above. We can call this the "force.com proxy" model.

Getting started

The following instructions will be useful if you want to build and deploy a Connected App which talks to the force.com APIs. If you are interested in building an app directly on Salesforce1, checkout the Force.com Workbook Tutorial for help getting started.

Before writing any code, I recommend that people try out the force.com APIs to get a sense of how they work. First, register for a free "Developer Edition" Salesforce account: https://developer.salesforce.com/. These trial accounts are free but include full API access and all developer tools.

Now open a tool called the Salesforce Workbench:

https://workbench.developerforce.com/login.php

The workbench makes it very easy to browse the Salesforce data model and all the Salesforce APIs. Your developer account will have preset data that you can query and modify.

Authentication

The first step to using any of the force.com APIs is to authenticate in to Salesforce. There are two primary mechanisms to do this:

1. Oauth web flow. This is an Oauth2 standard flow. Use this mechanism when each user of your app will have their own Salesforce login.

2. Password + token login. If you are using the "single API user" approach, then the simplest authentication approach is to send a username and password to the API login endpoint. For increased security however it isn't sufficient to provide just the password. You also need to present a 'security token'. Login to Salesforce with your API user account, then go to My Settings -> Personal -> Reset My Security Token and click the green button. Salesforce will send you a security token by email.

Accessing the API

There are a variety of SDKs that make accessing the Force.com APIs very easy. Pick a library that works with your language and get it installed.

For the examples below I will show a Ruby example, using the Restforce library, and a Node.js example using the Nforce library.

You can install one of these as follows:

$ gem install restforce
$ npm install nforce

To connect to Salesforce you need to define a Connected App in your Salesforce account. Follow these instructions to create your Connect App. The Connected App creates an Oauth consumer key and secret which you need to authenticate to the force.com API.

Note that even though you create a Connected App inside of one Salesforce account, your app can access any Salesforce acccount using the same Oauth credentials.

Gather the following pieces of information for accessing the Force.com API:

1. Oauth consumer key
2. Oauth consumer secret
3. Oauth redirect URI
4. API user username
5. API user password
6. API user security token

A good practice is to set all of these values in the environment for your app. On Heroku you can set config vars ('heroku config:set name=value') for these values.

Note that if you are using the "API user" pattern, then the Oauth redirect URI can be any value that you want, but it must match the value you entered into the Connected App.

Now, we are actually in position to authenticate into Force.com:

Ruby example

require 'restforce'

client = Restforce.new :username => 'foo',
  :password       => 'bar',
  :security_token => 'security token',
  :client_id      => ENV['SF_OAUTH_CLIENT_ID'],
  :client_secret  => ENV['SF_OAUTH_CLIENT_SECRET']

Node example

var nforce = require('nforce');

var org = nforce.createConnection({
  clientId: process.env('SF_OAUTH_CLIENT_ID'),
  clientSecret: process.env('SF_OAUTH_CLIENT_SECRET'),
  redirectUri: 'http://localhost:3000/oauth/_callback'
});

org.authenticate({ username: username, password: password + token}, function(err, resp){
    // Use 'org' ...
});

Reading data

Salesforce data follows a relational model. Instead of 'table' however, Salesforce refers to 'objects', such as 'Contact' and 'Account'. One row from the table is referred to as an "instance" or more typically a "record".

Reading data is very easy. Force.com supports a simplified varient of SQL called SOQL. Let's see how to read 20 Account records from Salesforce:

Ruby example

accounts = client.query("select Id, Name, AccountNumber from Account limit 20")

Node example

var accounts = org.query({ query: 'select Id, Name, AccountNumber from Account limit 20' }, function(err, resp){
if(!err && resp.records) {
    resp.records.forEach(function(account) {
        console.log(account.get('Name'));
    });
}

Writing data

To write new records, just create an empty object of the correct type and save it.

Ruby example

client.create('Account', Name: 'Foobar Inc.', AccountNumber: 'ACT101')

Node example

var acc = nforce.createSObject('Account');
acc.set('Name', 'Foobar Inc.');
acc.set('AccountNumer', 'ACT101');

org.insert({ sobject: acc }, function(err, resp){
  if(!err) console.log('Account inserted');
});

Going further

The Heroku Mobile template provides a full example for accessing Force.com from your web server app.

Hopefully these instructions have gotten you started working with the Force.com APIs. There are lots of other resources out there with more information including the StackExchange group dedicated to Saleforce development.