Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
pom.xml REST API Connector

Lightweight library for building apps with OAuth authentication and data access through the REST API.


You can either include as a dependency and pull the module from its github maven repo or you can build locally.

Dependency on published release

The version number is bumped regularly. Check the tags list or commit messages for latest version.


        <name>force-rest-api repository on GitHub</name>



Build and link locally

$ git clone
$ cd force-rest-api
$ mvn install -DskipTests


The latest HEAD always builds to a snapshot:


Authentication and Instantiation

Username / Password Authentication

Authenticate using just login and password and get an account record:

DataApi api = new DataApi(new ApiConfig()

OAuth Username/Password Authentication Flow

As documented here

DataApi api = new DataApi(new ApiConfig()

OAuth Web Server Flow

As documented here

String url = Auth.startOAuthWebServerFlow(new AuthorizationRequest()
    .apiConfig(new ApiConfig()

// redirect browser to url
// Browser will get redirected back to your app after user authentication at
// with a code parameter. Now do:

ApiSession s = Auth.completeOAuthWebServerFlow(new AuthorizationResponse()
    .apiConfig(new ApiConfig()

DataApi api = new DataApi(s.getApiConfig(),s);

Instantiate with existing accessToken and endpoint

If you already have an access token and endpoint (e.g. from a cookie), you can pass an ApiSession instance to DataApi:

ApiConfig c = new ApiConfig()

ApiSession s = new ApiSession()

DataApi api = new DataApi(c,s);

CRUD and Query Operations

Get an SObject

Account res = api.getSObject("Account", "001D000000INjVe").as(Account.class);

This assumes you have an Account class defined with proper Jackson deserialization annotations. For example:

import org.codehaus.jackson.annotate.JsonIgnoreProperties;
import org.codehaus.jackson.annotate.JsonProperty;

public class Account {

    String id;
    String name;
    private Double annualRevenue;
    String externalId;  

    public String getId() { return id; }
    public void setId(String id) { = id; }
    public String getName() { return name; }
    public void setName(String name) { = name; }
    public Double getAnnualRevenue() { return annualRevenue; }
    public void setAnnualRevenue(Double value) { annualRevenue = value; }
    public String getExternalId() { return externalId; }
    public void setExternalId(String externalId) { this.externalId = externalId; }

Create SObject

Account a = new Account();
a.setName("Test account");
String id = api.createSObject("account", a);

Update SObject

a.setName("Updated Test Account");
api.updateSObject("account", id, a);

Create or Update SObject

a = new Account();
a.setName("Perhaps existing account");
api.createOrUpdateSObject("account", "externalId__c", "1234", a);

Delete an SObject

api.deleteSObject("account", id);

Query SObjects

QueryResult<Account> res = api.query("SELECT id FROM Account WHERE name LIKE 'Test account%'", Account.class);

Run Tests

This project currently only has integration-y tests (they hit the actual API). To make them work copy src/test/resources/ to src/test/resources/ and replace the properties in the file with actual values

Login and password

Add your developer org login and password. Needless to say, don't use credentials for a production org containing sensitive data. If you don't have a developer org, sign up for one. It's free.

Client ID and Secret

Once you have signed up for an org, navigate to the Remote Access Setup:

  • Click on "Admin User" drop-down in upper-right
  • Select Setup
  • In the left-side navigation pane, under "App Setup", click on "Develop"
  • Select "Remote Access"

Now create a new Remote Access Application:

  • Click on "New"
  • Choose any name for your application
  • Choose any callback URL (you'll need to set this properly when web server flow is supported)
  • Choose some contact email
  • Click "Save"
  • Copy "Consumer Key" to the property "clientId" in
  • Click on "Click to reveal" and copy "Consumer Secret" to "clientSecret" in

Add externalId__c to Account SObject

Use the Web UI to add a custom field called externalId__c and mark it as an external ID field:

  • (sorry, you have to figure out how to do this yourself. Will add instructions or automate it later)

Now run tests with

$ mvn test

Cutting a Release

This project uses the Maven release plugin with Github pages as Maven repo to facilitate quick releases. Snapshots are never released. They are reserved for local builds. See Christian Kaltepoth's post for an excellent guide to setting up Github pages as a maven repo. To cut a release: (adjust repo references as necessary below if you're on a fork or doing this on your own repo)

Clone this repo

$ git clone

Clone the github pages branch of this repo into release-repo sub-dir

$ cd force-rest-api
$ git clone -b gh-pages release-repo

Prepare a new release

Set up your test properties as described above in the testing section. Tests must pass. Edit pom.xml and adjust the SCM information to match your repo and github info if different from this one. Run

$ mvn release:prepare

This will create a couple of commits and push to your github repo. A new release has now been created and snapshotted in github, but it has not yet actually been built and deployed.

Build and deploy the new release

You can't use mvn release:perform because it will be missing your test fixture. Instead just do it manually. Check out the commit that was tagged as the new release. Something like:

$ git checkout force-rest-api-0.0.4

Build and deploy

$ mvn clean deploy -DupdateReleaseInfo

Commit the new release and push to gh-pages

$ cd release-repo
$ git add .
$ git commit -m "Release 0.0.4"
$ git push origin gh-pages

Clean up

$ cd ..
$ mvn release:clean

(deletes temporary and backup files)

$ git checkout master

gets you back to master from detached HEAD.

Project Goals:

  • Make it as thin as possible
  • Few or no dependencies
  • Other projects will handle generation of typed SObject classes and it should work here
  • Automatic session renewal
  • Pluggable JSON kit
  • Make sure it's Spring friendly. This solution may be necessary.


BSD 3-clause license


Jesper Joergensen

Something went wrong with that request. Please try again.