Using SOAP or REST to integrate with Platform

The topics in this section discuss how to access Platform application data programmatically for integration and extension purposes. When building integrations or external data manipulation tools that need to communicate with Platform programmatically, you can use the Platform SOAP or REST APIs. The SOAP and REST APIs expose the same functionality and use the same method names. A metadata API for both SOAP and REST provides methods for creating and manipulating definitions of applications, objects, fields, and relationships. The account under which metadata methods are invoked must have administrative privileges.

SOAP API

Platform uses literal WSDL encoding. If your SOAP infrastructure does not support literal WSDL encoding, consider using the REST API. To make SOAP calls, the client must have a valid Platform user account with login credentials. API users must have permission to view, create, update, or delete records to perform these actions via SOAP API calls; the documentation for each SOAP API method specifies the required permissions. Permissions cannot be set via the API; they can only be set by an administrator using the Platform user interface.

The Platform SOAP API uses the same workflow mechanism as the standard Platform user interface. For example, triggers designed to run on object record creation will run if a record is created through the SOAP API. The Platform SOAP API uses the same permissions mechanism as the standard Platform user interface.

To establish a SOAP API session, call the login() method, which takes user name and password credentials. The login() call returns a session ID that must be used as the first parameter in all subsequent API calls. To end a SOAP API session, call the logout() method.

See Platform SOAP Methods and SOAP Metadata Methods for descriptions of the available SOAP methods.

REST API

REST calls require authentication and are subject to the same security procedures as normal user log ins. To use this API requires a valid Platform user account with login credentials. The account must have permission to view, create, update, or delete records to perform these actions using REST calls; the documentation for each REST API specifies the required permissions. Permissions cannot be set via the API; they can only be set by an administrator using the Platform user interface.

Supply user credentials in one of the following ways:

  • Using a session ID — Call the login AP with valid credentials to receive a session ID. Supply that session ID in every REST call as an HTTP header or URL parameter. At the end of session, call logout to end the REST session. For example, this PHP code sets the HTTP header: header('sessionId: '.$sessionId); This example passes the session ID in the URL: &sessionId=1776eb2d56384f2d9d62f1bf83821b6d@5857
  • By providing basic HTTP authentication through the HTTP header — Append @ and and the customer ID to the login name. A PHP code example:
    $header = base64_encode($userName.'@'.$custId.':'.$password); header('Authorization: Basic '.$header);

Private cloud master tenant users can use their credentials to call the REST API on a specified tenant. REST API calls using a session ID or basic authentication are considered to be made from behalf of the logged in user. Permissions of that user are checked for each subsequent call. For instance, to update a record logged in user must have EDIT permissions on that record, of API call will fail. Use of a session ID is preferred in terms of performance and security.

See Platform REST Methods and REST Metadata Methods for descriptions of the available REST methods.