Force.com REST Resources

A REST resource is an abstraction of a piece of information or an action, such as a single data record, a collection of records, or a query. Each resource in REST API is identified by a named Uniform Resource Identifier (URI) and is accessed using standard HTTP methods (HEAD, GET, POST, PATCH, DELETE). REST API is based on the usage of resources, their URIs, and the links between them.

You use a resource to interact with your Salesforce org. For example, you can:

Retrieve summary information about the API versions available to you.
Obtain detailed information about a Salesforce object, such as Account, User, or a custom object.
Perform a query or search.
Update or delete records.

Suppose you want to retrieve information about the Salesforce version. Submit a request for the Versions resource.

1curl https://yourInstance.salesforce.com/services/data/

The output from this request is as follows.

1[
2    {
3        "version":"20.0",
4        "url":"/services/data/v20.0",
5        "label":"Winter '11"
6    }
7    ...
8]

Salesforce runs on multiple server instances. The examples in this guide use yourInstance in place of a specific instance. Replace that text with the instance for your org.

Note

Important characteristics of the Force.com REST API resources and architecture:

Stateless

Each request from client to server must contain all the information necessary to understand the request, and not use any stored context on the server. However, the representations of the resources are interconnected using URLs, which allow the client to progress between states.

Caching behavior

Responses are labeled as cacheable or non-cacheable.

Uniform interface

All resources are accessed with a generic interface over HTTP.

Named resources

All resources are named using a base URI that follows your Force.com URI.

Layered components

The Force.com REST API architecture allows for the existence of such intermediaries as proxy servers and gateways to exist between the client and the resources.

Authentication

The Force.com REST API supports OAuth 2.0 (an open protocol to allow secure API authorization). See Understanding Authentication for more details.

Support for JSON and XML

JSON is the default. You can use the HTTP ACCEPT header to select either JSON or XML, or append .json or .xml to the URI (for example, /Account/001D000000INjVe.json).

The JavaScript Object Notation (JSON) format is supported with UTF-8. Date-time information is in ISO8601 format.

XML serialization is similar to SOAP API. XML requests are supported in UTF-8 and UTF-16, and XML responses are provided in UTF-8.

Friendly URLs

Why make two API calls when you can make just one? A friendly URL provides an intuitive way to construct REST API requests and minimizes the number of round-trips between your app and Salesforce org. Friendly URLs are available in API version 36.0 and later.

Accessing a contact’s parent account without a friendly URL involves requesting the contact record using the SObject Rows resource. Then you examine the account relationship field to obtain the account ID and request the account record with another call to SObject Rows. Using a friendly URL, you can access the account in a single call directly from the contact’s path: /services/data/v36.0/sobjects/contact/id/account.

This functionality is exposed via the SObject Relationships resource. For more examples of using friendly URLs to access relationship fields, see Traverse Relationships with Friendly URLs.

Force.com REST API Developer Guide

Force.com REST Resources