Force.com REST API Developer Guide

Introducing Force.com REST API
Quick Start
Prerequisites
Step One: Obtain a Salesforce Developer Edition Organization
Step Two: Set Up Authorization
Step Three: Send HTTP Requests with cURL
Step Four: Walk Through the Sample Code
Using Workbench
Examples
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Step Three: Send HTTP Requests with cURL

To interact with the Force.com REST API, you need to set up your client application (we use cURL) to construct HTTP requests.

Setting Up Your Client Application

The REST API uses HTTP GET and HTTP POST methods to send and receive JSON and XML content, so it is very simple to build client applications using the tool or the language of your choice. We use a command-line tool called cURL to simplify sending and receiving HTTP requests and responses.

cURL is pre-installed on many Linux and Mac systems. Windows users can download a version at curl.haxx.se/. When using HTTPS on Windows, ensure that your system meets the cURL requirements for SSL.

Sending HTTP Requests Using REST API Resources

Your HTTP requests to a REST API resource should contain the following information:
  • An HTTP method (HEAD, GET, POST, PATCH, or DELETE).
  • An OAuth 2.0 access token used to authenticate the request. For information on how to retrieve the token, see Quick Start.
  • An HTTP ACCEPT header used to indicate the resource format (XML or JSON), or a .json or .xml extension to the URI. The default is JSON.
  • The Force.com REST resource.
  • Any JSON or XML files containing information needed for requests, such as updating a record with new information.
The HTTP methods are used to indicate the desired action, such as retrieving information, as well as creating, updating, and deleting records.
  • HEAD is used to retrieve resource metadata.
  • GET is used to retrieve information, such as basic resource summary information.
  • POST is used to create a new object.
  • PATCH is used to update a record.
  • DELETE is used to delete a record.

To access a resource, submit an HTTP request containing a header, method, and resource name.

For example, assume you want to create an Account record using a JSON-formatted file called newaccount.json. It contains the information to be stored in the new account:
1{
2    "Name" : "test"
3}
Using cURL on your instance, the request would appear as follows: 
1curl https://yourInstance.salesforce.com/services/data/v20.0/sobjects/Account/ -H "Authorization: Bearer token -H "Content-Type: application/json" -d "@newaccount.json"

The request HTTP header:

1POST /services/data/v20.0/sobjects/Account HTTP/1.1
2User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.8l zlib/1.2.3
3Host: yourInstance.salesforce.com
4Accept: */*
5Content-Length: 1411
6Content-Type: application/json
7Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8X-PrettyPrint:1
The response:
1Date: Thu, 21 Oct 2010 22:16:22 GMT 
2Content-Length: 71 
3Location: /services/data/v20.0/sobjects/Account/001T000000NU96UIAT 
4Content-Type: application/json; charset=UTF-8 Server:
5{ "id" : "001T000000NU96UIAT", 
6  "errors" : [ ],
7  "success" : true }

For a list of the resources and their corresponding URIs, see Reference.