REST APIs

An API specifies how software components should interact with each other.

The following are some of the important concepts to know before using the CL Originate API (Application Programming Interface):

1. The CL Originate API is organized around REST (Representational State Transfer) and is designed to have predictable and resource-oriented URLs (Uniform Resource Locators). 

2. The API is designed to use the following:

   • HTTP (Hypertext Transfer Protocol) response codes to indicate the API Errors.

   • Built-in HTTP features such as the HTTP verbs which can be understood by off-the-shelf HTTP clients.

   • Standard Salesforce authentication protocol.

3. JSON (JavaScript Object Notation) is returned in all responses from Web Services, including errors, and is the expected input format of requests in POST methods.

4. The expected request parameters including mandatory fields and the request method (ie., GET or POST) along with the expected responses for all the Web Services provided by CL Originate are described here.

5. Understanding the request: The requested URL is typically structured as follows:

   Copy

   https://<domain>/services/apexrest/<namespace>/v1/<object>/<operation>/<id>?
   <key value pair of parameters if this is a GET request><domain> 
   => "instance_url" field in the response you receive when you get authenticated from SalesForce
    as explained in point G below.
   <namespace> => Namespace, which is "genesis".
   v1 => version of API which is currently "v1".
   <object> => SalesForce Standard/Custom Object which we want to perform operations on.
    SObject name should be in plural.
   <operation> => Optional. Operation we want to perform on a record of <object> and 
   record is identified by <id>. 
                  If no operation is present and method is GET, Web Service will return a record of the
    <object> identified by <id> 
                  or as documented in the Web Service (All Web Services may not support, 
   check particular Web Service 
                  documentation in References). If no operation is present and method is POST,
    Web Service will create a record with
                  parameters specified in request body.
   <id> => Optional. Unique Id of <object> and used as specified above.

6. Reading the response: The response from any Web Service is organized and can be interpreted as follows:

   Copy

   {
       "status" => Either "SUCCESS" or "ERROR",
       "response" => Any data other than SalesForce SObjects, we will term it as Custom Response in this document. This is an array of Apex Custom Objects (Please note this is not a SalesForce Custom Object which is custom SObject),
       "errorMessage"=> Detailed message if "status" is "ERROR",
       "errorCode"=> A short description of the error if "status" is "ERROR". Every Web Service explains possible error codes and its possible causes. 
       "content": => An array of SalesForce SObjects on which we are performing the action.
   }

7. Authentication to the API occurs by a Salesforce authentication. When you request data from Salesforce within the external application, you must be authenticated by Salesforce. The authentication contains several steps, as dictated by the OAuth standard.

   For more information, see <https://help.salesforce.com/HTViewHelpDoc?id=remoteaccess_oauth_username_password_flow.htm&language=en_US>.
   

   Note:

   All the requests must be authenticated.

8. Errors: All the errors are returned in JSON. 

   The HTTP status codes can be summarized as shown in the following table:

   HTTP Status Code	Diagnosis
   200 OK	Everything worked
   400 Bad Request	Invalid parameter or data integrity issue
   401 Unauthorized	Authentication error
   404 Not Found	Resource not found
   405 Method Not Allowed	Method not supported by the resource
   500 Internal Server Error	Platform Internal Server error