REST API Concepts

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

The following are some of the important concepts to know before using the Q2 Loan Servicing and Q2 Marketplace API (Application Programming Interface):

1. The Q2 Loan Servicing and Q2 Marketplace 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 (GET or POST) along with the expected responses for all the Web Services provided by Q2 Loan Servicing and Q2 Marketplace are described here. 

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

   Request

   Copy

   https://<domain>/services/apexrest/<namespace>/v1/<object>/<operation>/<id>?<key value pair of parameters if this is a GET request>

   Where:

   • <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 "peer".

   • 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:

   Response

   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 for 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 here.

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

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

   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