Getting Started with Force.com REST API
Data access concepts in Force.com translate naturally into the REST style of API. SObjects and rows within them become URLs, and HTTP actions express DML operations: GET for read-only requests for basic information, POST to create records, PATCH to update records, and DELETE to delete them. Because not all HTTP clients support the full range of methods, Force.com also allows a special URL parameter (_HttpMethod) to specify the action. By default, REST API calls return JSON-encoded responses, but you can override this by appending .xml to the end of URLs, or by sending the standard HTTP Accept header with the desired content type.
Almost every REST API call requires authentication to Force.com. This is done using OAuth. OAuth is an industry-standard way of negotiating access to a system without requiring users to share their login credentials. OAuth operates using tokens instead. Tokens have advantages over the typical username/password credentials. They can be audited and revoked by the user. They also typically provide limited access to the system. In the case of Force.com, OAuth access tokens grant bearers the ability to make API calls only. They cannot log in to the Salesforce Web user interface.
OAuth is a complex subject well beyond the scope of this book. The Force.com REST API Developer’s Guide, found at www.salesforce.com/us/developer/docs/api_rest/index.htm, provides some introductory information on using OAuth to authenticate to Force.com.
If you are calling the REST API on behalf of another user, OAuth is the recommended approach for authentication because you do not need to store others’ usernames and passwords. But when you’re learning and experimenting with simple REST API examples, OAuth can present a significant hurdle.
A shortcut is to use the username-password OAuth flow, which still accepts username and password directly. Listing 10.4 provides a sample request and response.
Listing 10.4 Sample Password Authentication Request and Response
curl https://login.salesforce.com/services/oauth2/token
-d "grant_type=password" -d "client_id=$CLIENT_ID"
-d "client_secret=$CLIENT_SECRET"
-d "username=$USERNAME" -d "password=$PASSWORD"
{
"id": "https://login.salesforce.com/id/...",
"issued_at": "1374386510993",
"instance_url": "https://na15.salesforce.com",
"signature": "...",
"access_token": "..."
}
The value in the response’s access_token field is needed to run all of the examples in this section. To get one yourself, set the $USERNAME environment variable to your Salesforce username, $PASSWORD to your Salesforce password with security token appended. The variables $CLIENT_ID and $CLIENT_SECRET are your OAuth Consumer Key and Consumer Secret. These come from a Connected App, which you can create using the following steps:
1. In the App Setup area, click Create, Apps.
2. Click the New button in the Connected Apps section.
3. Fill out Connected App Name, API Name, and Contact Email.
4. Check Enable OAuth Settings.
5. Set the Callback URL to http://localhost.
6. In Available OAuth Scopes, select Access and Manage Your Data (api).
The resulting Connected App is shown in Figure 10.1.
