3Getting Started with the Oracle CRM On Demand REST API
Getting Started with the Oracle CRM On Demand REST API
This chapter provides an overview of how to get started with using the REST API in Oracle CRM On Demand. It contains the following topics:
Oracle CRM On Demand REST API Privilege Required
To send requests and manage RESTful Services Integration, your user role must include the privilege: Restful Services Integration. Contact Oracle Customer Care if you do not have the privilege.
About Oracle CRM On Demand REST API Authentication
The Oracle CRM On Demand REST API uses Oracle CRM On Demand authentication. To use the Oracle CRM On Demand REST API with Oracle CRM On Demand, you must have a valid Oracle CRM On Demand user account to establish a secure session with the Oracle CRM On Demand server. There are several different ways in which Oracle CRM On Demand server sessions can be established and maintained:
You can log into the Oracle CRM On Demand server through the Oracle CRM On Demand user interface. You must be successfully signed in to Oracle CRM On Demand to send REST API requests and receive REST API responses. If you are not signed in to Oracle CRM On Demand, and if you try to send a REST API request, then you will receive an HTTP 403 forbidden status code. For more information about HTTP status codes, see Standard HTTP Status Codes.
You can use the Oracle CRM On Demand REST API connection request to establish a session with the Oracle CRM On Demand server using a JSESSIONID cookie. For more information about using the Oracle CRM On Demand REST API connection request to establish an Oracle CRM On Demand server session, see Login with Oracle CRM On Demand REST API.
You can use the Oracle CRM On Demand REST API and your SSO ID URL parameter to log into the Oracle CRM On Demand server. For more information regarding SSO, Using SSO with the Oracle CRM On Demand REST API.
If authentication is unsuccessful, the Oracle CRM On Demand server returns an HTTP 401 unauthorized status code and you are prompted to authenticate again. If the Oracle CRM On Demand server returns an HTTP 302 found code, the Oracle CRM On Demand checks the login server to confirm if the user is authenticated. If you are authenticated, then you are redirected to the correct URL. For more information about HTTP status codes, see Standard HTTP Status Codes.
Login with Oracle CRM On Demand REST API
You can use the Oracle CRM On Demand REST API connection request to initiate an Oracle CRM On Demand server session.
You can request an Oracle CRM On Demand server session and obtain a valid session ID by sending an HTTP GET request to the following URL:
/OnDemand/user/Rest/Connection Request Header: Authorization: Basic cmVzdC91c2VyMTpVc2VyMTI4NQ==
In the example above, the authorization was added as a request header that has the value of the username followed by a colon and then the password encoded in Base 64. A basic string was added to indicate basic authentication.
A successful logon request returns an HTTP status code of 200 and the JSESSIONID is returned in the JSESSION response header. For more information about HTTP status codes, see Standard HTTP Status Codes.
If the Oracle CRM On Demand server session times out for any reason, the error returned reports that the session is not valid and you must then request a new Oracle CRM On Demand session.
After local authentication, Oracle CRM On Demand authenticates you against the login server when an application makes a REST API request. After credentials are authenticated, Oracle CRM On Demand executes the REST API request, allowing you to interact with the Oracle CRM On Demand server to perform data retrieval, modification, creation, and deletion operations. The REST API response returns a valid JSESSIONID value, which is used for authenticating subsequent requests. The response also includes metadata about the connection session. For more information about connection attributes, see REST API Connection Attributes.
REST API Connection Attributes
After credentials are authenticated, the Oracle CRM On Demand server returns a response to the REST API connection request that includes connection attributes. The REST API connection attributes provide details about the current user and the current Oracle CRM On Demand server session.
The following table contains the connection attributes returned in a REST API connection request.
Table Connection Attributes
| Connection Attribute | Description |
|---|---|
apiVersion |
The latest version of the Oracle CRM On Demand REST API. |
apiVersionMinimum |
The oldest version of the Oracle CRM On Demand REST API. |
clientHelpURL |
The URL for the page that describes Oracle CRM On Demand REST API errors. |
dateFormatLocale |
The date and time format. |
languageLocale |
The expected language code for REST API requests that matches the locale code of the logged-in user language. |
maximumFileSize |
The maximum file size in MB supported for attachments. |
Version |
The current Oracle CRM On Demand version number. |
ServerDate |
The current date/time in REST API date format. |
ITSUrlforSSO |
The Security Assertion Markup Language (SAML) Intersite Transfer Service URL that is used for Single Sign-On (SSO) into Oracle CRM On Demand. |
LastLoggedIn |
The date that the user last logged in. |
UserLoginId |
The user login ID. |
UserId |
The user ID returned. |
TenantId |
The tenant ID returned. |
CompanyName |
The company name returned. |
REST API Connection Attributes Example
The connection attributes are returned when you send a request to log into an Oracle CRM On Demand server session.
To return the connection attributes, send an HTTP GET request to the following URL:
/OnDemand/user/Rest/Connection
The REST API request returns the connection response with the following attributes. Some values of the attributes are context-sensitive. For more information about connection attributes, see REST API Connection Attributes.
{
"Connection": {
"apiVersion": "028",
"apiVersionMinimum": "026",
"clientHelpURL": "https://support.oracle.com/epmos/faces/DocumentDisplay?id=1802485.1",
"dateFormatLocale": "yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:ss'Z'",
"languageLocale": "ENU",
"maximumFileSize": 20,
"Version": "028.009.000",
"ServerDate": "2014-12-10T10:55:36Z",
"LastLoggedIn": "2014-12-08T13:22:41Z",
"UserLoginId": "REST/USER1",
"UserId": "1QA2-21ATBK",
"TenantId": "1QA2-21AI7F",
"CompanyName": "rest"
}
}
Logoff with Oracle CRM On Demand REST API
You can use the Oracle CRM On Demand REST API connection request logoff action to terminate an Oracle CRM On Demand session.
You can request to terminate an Oracle CRM On Demand server session by sending an HTTP GET or POST request to the following URL:
/OnDemand/user/Rest/Connection?action=logoff
A successful logoff request returns an HTTP status code of 200. For more information about HTTP status codes, see Standard HTTP Status Codes.
Using SSO with the Oracle CRM On Demand REST API
The Oracle CRM On Demand REST API Single Sign-On (SSO) feature is a session and user authentication process that allows you to enter one name and password in order to access multiple applications, without having to enter your log-on credentials a second time. You can use the REST API Single Sign-On (SSO) feature to initiate an Oracle CRM On Demand server session and to manage user credentials and authentication. The REST API SSO login feature uses the Oracle CRM On Demand SSO login mechanism. For more information about Oracle CRM On Demand SSO, see Oracle CRM On Demand Online Help.
Before you can use the Oracle CRM On Demand REST API SSO feature to log into Oracle CRM On Demand, you need to do the following:
Verify whether your company is configured to use the Oracle CRM On Demand SSO feature by checking the Authentication Type value set in your company profile and verify that the Authentication Type is set to Single Sign-On Only or User ID/PWD or Single Sign-On. For more information about the Authentication Type setting in the Oracle CRM On Demand company profile, see Oracle CRM On Demand Online Help.
Verify that your company is configured for SSO logon for Oracle CRM On Demand by checking the ITS URL for SSO Authentication value in your company profile. The SAML Intersite Transfer Service URL is used for signing in to Oracle CRM On Demand and the company administrator sets this value. Contact Oracle CRM On Demand Customer Care to obtain an SSO worksheet that contains instructions for setting the ITS URL.
If your company is configured to use Oracle CRM On Demand SSO, you will need the External Identifier for Single Sign-On value set in your company profile. For more information about the External Identifier for Single Sign-On setting in your company profile, see Oracle CRM On Demand Online Help.
You can request a SSO Oracle CRM On Demand server session by sending an HTTP GET or POST request specifying the SSO ID to the following URL:
/OnDemand/user/Rest/Connection?ssoid=<ID>
The Oracle CRM On Demand server returns the ITS URL value, which can then be used in a prompt for authentication credentials.
About Customizing REST Integration Tags
Your company can rename Oracle CRM On Demand record types or use custom record types. For example, the Account record type might be renamed Companies. To allow for this, you can customize the record type (resource) tag name referenced in Oracle CRM On Demand REST API URLs.
The Oracle CRM On Demand REST API resource can be accessed by both the default tag name and the custom tag name that you create. For example, Accounts is the default tag name for the Account record type. If you create a custom tag name, Companies, for the Account record type, then accounts can be accessed by both of the following URLs:
https://<host>/OnDemand/user/Rest/latest/Accounts https://<host>/OnDemand/user/Rest/latest/Companies
Customizing REST API Integration Tags
The following procedure describes how to customize the REST API integration tags that you use in REST API URLs. You can view the available integration tags in the REST Integration Tags page in the Oracle CRM On Demand user interface.
To customize REST integration tags
In the upper-right corner of any page, click the Admin global link.
In the Application Customization section, click Application Customization.
Click the Customize REST Integration Tags link.
In the REST Integration Tags list, click the Edit link for the record type.
In the REST Integration Tag field, enter the new name and click Save.
Using JavaScript to Send REST API Requests
You can use an XMLHttpRequest JavaScript object to send REST API requests to the Oracle CRM On Demand Server. An XMLHttpRequest object allows you to send GET, POST, PUT or DELETE requests. Your request can also include the format for the response, for example, JSON or XML.
The example in this topic is a sample of JavaScript code that makes a REST API call to get the Accounts collection. The JavaScript then converts the response output into a JSON object and outputs a screen alert with the number of accounts in the collection that is visible to the user.
In the example below, accounts are accessed using the default Accounts tag name, that is, Accounts has not been renamed or customized. In addition, the visible accounts do not exceed the default limit of 100 for the user, because the example does not use the limit or paging arguments. For an example of retrieving accounts using limit and paging arguments, see Retrieving a Collection Top-Level Resource List.
To use JavaScript to send REST API requests to the Oracle CRM On Demand Server, you must have access to Oracle CRM On Demand and be successfully logged into the Oracle CRM On Demand Server. For more information about REST API privileges, see Oracle CRM On Demand REST API Privilege Required. For more information about logging into Oracle CRM On Demand, see Login with Oracle CRM On Demand REST API.
var xhr = new XMLHttpRequest();
xhr.open("GET", "/OnDemand/user/Rest/latest/Accounts", true);
xhr.onload = function (e) {
if (xhr.readyState === 4) {
if (xhr.status === 200) {
var respJSON = JSON.parse(xhr.responseText);
alert(respJSON.Accounts.length);
} else {
//console.error(xhr.statusText);
//handle error status
}
}
};
xhr.onerror = function (e) {
console.error(xhr.statusText);
};
xhr.send(null);