Which Salesforce API to Use When

Salesforce REST API

Access to objects in your instance using a REST-style interface. Performs record-level CRUD operations, and queries and searches. Enables you to work with object metadata, approval processes, and process rules.

See the Force.com REST API Developer Guide.

You want to leverage the REST architecture to integrate with your Salesforce instance programmatically. There is no WSDL requirement, which makes this API easier to use. This API is better suited than the SOAP APIs for browser-based applications, mobile apps, and highly-interactive social applications.

REST

JSON, XML

Synchronous

SOAP API

Integrates your organization’s data with other applications using SOAP. The SOAP API comes in two forms: the Enterprise WSDL, which is a strongly-typed representation, and the Partner WSDL, which is a weakly-typed representation, so the WSDL does not change across instances or as the underlying object model changes.

See the SOAP API Developer Guide.

You have pre-existing middleware services that must work with WSDLs and XML data. If you do not specifically need SOAP access using WSDL definitions, use the REST APIs instead.

SOAP, WDSL

XML

Synchronous

Chatter REST API

Displays Chatter-related data, especially in mobile apps. Works with Chatter feeds, users, groups, and followers; Salesforce Files and Files Connect; or recommendations, topics, notifications, Data.com, and other Salesforce features.

See the Chatter REST API Developer Guide.

You want to integrate Chatter-related functionality into a mobile app, intranet site, or third-party web application.

REST

JSON, XML

Synchronous (photos are processed asynchronously)

Bulk API

Loads or deletes large numbers of records asynchronously by submitting batches that are Salesforce processes in the background. The Bulk API is based on REST principles. You can use it to query, insert, update, upsert, or delete a large number of records.

See the Bulk API Developer Guide.

You have more than one million records to process and speed is required.

REST

CSV, XML

Asynchronous

Metadata API

Manages customizations in your organization and builds tools that can manage the metadata model, not the data itself.

See the Metadata API Developer Guide.

You want to migrate changes, such as custom object definitions and page layouts, from a sandbox to your production environment.

SOAP, WDSL

XML

Asynchronous

Streaming API

Provides a stream of data reflecting data changes in your organization.

For more information, see the Force.com Streaming API Developer Guide.

You need near real-time notifications of when records are created or updated.

Bayeux

JSON

Asynchronous (stream or data)

Apex REST API

Enables you to build your own REST API in Apex. Exposes Apex classes as RESTful web services. Apex REST API supports both OAuth 2.0 and Session ID for authorization.

See Exposing Apex Classes as REST Web Services in the Force.com Apex Code Developer Guide.

You need to build custom JSON responses or you want to expose custom functionality that you implemented in Apex.

REST

JSON, XML, Custom

Synchronous

Apex SOAP API

Creates custom SOAP Web services in Apex. Exposes Apex classes as SOAP Web services. Apex SOAP API supports both OAuth 2.0 and Session ID for authorization.

See Exposing Apex Methods as SOAP Web Services in the Force.com Apex Code Developer Guide.

You need to build custom XML responses or you want to expose custom functionality that you implemented in Apex .

SOAP, WDSL

XML

Synchronous

Tooling API

Enables you to build custom development tools for Force.com applications. Manages and deploys working copies of Apex classes and triggers and Visualforce pages and components. Set checkpoints, or heap dump markers, execute anonymous Apex, and access logging and code coverage information. See Force.com Tooling API.

You want to add functionality to your existing development and integration tools. You want to build specialized development tools for a specific application or service.

REST, SOAP

JSON, XML, Custom

Asynchronous