Developer Guides

Introduction to RESTful APIs

Suggest Edits

Overview

Encompass Partner Connect (EPC) uses REST (Representational State Transfer) API to integrate partner services with a variety of ICE Mortgage Technology (IMT) products. This guide is an introduction to the REST architecture if you need a refresher. It uses Google Drive’s API to illustrate REST concepts.

REST is an API architecture for web services that most commonly uses HTTP for requests and JSON as a data format. REST systems are designed to be flexible, and optimized for the web.

REST primarily uses four HTTP methods to execute requests:

  • GET retrieves a resource (ex. Retrieves information about a Drive user)
  • POST creates a resource (ex. Creates a new file)
  • PUT updates a resource (ex. Updates a comment on a document)
  • DELETE removes a resource (ex. Deletes a file)

Requests

A request consists of an HTTP request, parameters, authorization, and a request body.

HTTP Request

The HTTP request consists of an HTTP method and a request URL. The request URL begins with the API domain and continues with a URI path that narrows the scope of the request to a specific resource.

For example, to receive a list of comments in a Google Drive file, the API domain https://www.googleapis.com/drive/v3/ is combined with the URI path /files/{fileID}/comments to create the request URL.

The complete HTTP request is
GET https://www.googleapis.com/drive/v3/files/{fileId}/comments

Parameters

Two key types of parameters are path parameters and query parameters:

  • The path parameter in the following request is {fileID} because it is part of the URI path.
    GET https://www.googleapis.com/drive/v3/files/{fileId}/comments
  • Query parameters tailor requests to return sorted or filtered resources. They appear after the ? symbol, and are separated from each other by the & symbol.

The request below has two query parameters: includeDeleted and pageSize.

GET https://www.googleapis.com/drive/v3/files/{fileID}/comments?includeDeleted=true&pageSize=50

includeDeleted returns deleted comments, and pageSize sets the maximum number of comments per page at 50.

Query parameters can be in any order. ?pageSize=50&includeDeleted=true returns the same response as ?includeDeleted=true&pageSize=50.

Authorization

You need authorization to access restricted data. The authorization method you use depends on the information you request. Some of the most popular authorization methods for APIs include:

  • API Keys
  • OAuth 2.0
  • OpenID Connect
  • SAML

Google Drive uses OAuth 2.0 for authorization that has various scopes. Each scope allows access to particular information. For example, to retrieve a list of comments on a Google Drive file, authentication is sent in a header to one of the following scopes:

https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.file

The authentication scopes for other requests might differ. For example, to create a comment on a Google Drive file, the authentication scopes are the /drive or /drive.file paths.

Request Body

The request body is where you send additional information to the server. Typical uses are to create or update comments, accounts, users, and others.

Below are the HTTP request and request body to create a comment on a Google Drive file.

{
  "content": "This is a new comment."
}

Response

The server sends a response after the request has been processed. The response contains the requested resource.

If the request is to create a new Google Drive comment, the response is:

{
	"kind": "drive#comment",
	"id": "AAAAD5zEPvw",
	"createdTime": "2019-11-01T20:30:27.646Z",
	"modifiedTime": "2019-11-01T20:30:27.646Z",
	"author": {
    	"kind": "drive#user",
    	"displayName": "Jane Doe",
    	"photoLink": "//ssl.gstatic.com/s2/profiles/images/silhouette96.png",
    	"me": true
	},
	"htmlContent": "This is a new comment.",
	"content": "This is a new comment.",
	"deleted": false,
	"replies": []
}

Below is a sample response to the request
GET https://www.googleapis.com/drive/v3/files/{fileId}/comments. It returns information about two comments. Notice that the latest comment is listed first, and that the oldest comment has an embedded reply resource.

{
	"kind": "drive#commentList",
	"comments": [
    	{
        	"kind": "drive#comment",
        	"id": "AAAADuQiSo4",
        	"createdTime": "2019-11-01T19:55:42.551Z",
        	"modifiedTime": "2019-11-01T19:55:53.415Z",
        	"author": {
            	"kind": "drive#user",
            	"displayName": "Anonymous",
            	"photoLink": "//ssl.gstatic.com/s2/profiles/images/silhouette96.png",
            	"me": false
        	},
        	"htmlContent": "This is the second comment.",
        	"content": "This is the second comment.",
        	"deleted": false,
        	"quotedFileContent": {
            	"mimeType": "text/html",
            	"value": "supernatural"
        	},
        	"anchor": "kix.uutwdb1shk0i",
        	"replies": [
            	{
                	"kind": "drive#reply",
                	"id": "AAAADuQiSo8",
                	"createdTime": "2019-11-01T19:55:53.415Z",
                	"modifiedTime": "2019-11-01T19:55:53.415Z",
                	"author": {
                    	"kind": "drive#user",
                    	"displayName": "Jane Doe",
                    	"photoLink": "//ssl.gstatic.com/s2/profiles/images/silhouette96.png",
                    	"me": true
                	},
                	"htmlContent": "This is a reply.",
                	"content": "This is a reply.",
                	"deleted": false
            	}
        	]
    	},
    	{
        	"kind": "drive#comment",
        	"id": "AAAADuQiSo0",
        	"createdTime": "2019-11-01T19:55:36.526Z",
        	"modifiedTime": "2019-11-01T19:55:36.526Z",
        	"author": {
            	"kind": "drive#user",
            	"displayName": "Anonymous",
            	"photoLink": "//ssl.gstatic.com/s2/profiles/images/silhouette96.png",
            	"me": false
        	},
        	"htmlContent": "This is the first comment.",
        	"content": "This is the first comment.",
        	"deleted": false,
        	"quotedFileContent": {
            	"mimeType": "text/html",
            	"value": "had"
        	},
        	"anchor": "kix.63k5vm6lydjv",
        	"replies": []
    	}
	]
}

Updated 6 months ago

What’s Next