REST API Concepts

  • Updated

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

A. 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). 

B. 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.

C. 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.

D. 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. 

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

Request

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

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

Response

{

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

}

G. 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.

H. 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

In This Article