Platform Rest APIs

Desk Invoke API

Desk's invoke API acts as a proxy between the extension and the External Services or Desk for calling the APIs.

With Desk Invoke API,

Can access the Zoho Desk's APIs
Can access the External Services's APIs
Can access the Extension Data Specific APIs such as storage, configParam and log APIs

Using Desk Invoke API

The query parameters such as orgId , securityContext and headerparam HASH are required for calling Invoke API . orgId & securityContext will be provided by desk during the Platform event callbacks. HASH should be generated using the SECRET and the Request URL inputs. Refer Generating Hash for Invoke API.

#INVOKE_API_REQUEST_PAYLOAD

Field	Required	Type	Description
securityContext	yes	string	An Extension specific encrypted token that is used for identifying & authenticating the extension while calling the invoke API. SecurityContext can be obtained during Platform event callbacks
requestURL	yes	string	URL to be invoked.
requestType	yes	string	HTTP method for invoking the requestURL For example, GET POST PATCH PUT DELETE
postBody	yes	string	Payload or body to be sent while invoking the requestURL.
headers	yes	string	Headers to be sent while invoking the requestURL.
queryParams	yes	string	QueryParams to be sent while invoking the requestURL.
connectionLinkName	yes	string	If the authorization needs to be applied from the connections while invoking the requestURL, specify the unique connection name provided by the DRE.

Generate Hash for Invoke API

To call invoke API, HASH is mandatory. Hash is used to verify the invoke API call was originally made by the extension developer. HASH is an HMAC sha256 encrypted string with the key as app's secret (manifest.secret) provided in the manifest and the input as invokeAPI's payload.

Desk also will generate the HASH with the shared app's secret with the provided payload in the invoke API and will match the provided HASH in the desk invoke API's header. If the HASH does not match with the desk generated HASH, then the invoke API will not be processed.

The same process of authentication can be used by the extension during the extension callback events to verify the callback was originally sent by the desk.

Sample of Invoke API HASH Generation

CopiedIf manifest.secret => "my_secret_key_238392"

For Sample Invoke API Inputs =>
requestURL          = https://api.google.com/test
requestType         = POST
queryParams         = {}
postBody            = {}
headers             = {"orgId":376723}
connectionLinkName  = myConnectionLinkName

(*ignore what you don't need)'

Hash generation would be =>
let stringToHash =
'requestURL=https://api.google.com/test&requestType=POST&queryParams={}&postBody={}&headers={"orgId":376723}&connectionLinkName=myConnectionLinkName'

then, generated HASH = hmac_sha256 ( stringToHash, "my_secret_key_238392" );

*Note: While generating HASH, only include the parameters which will be used in the 
 invoke API.
Order of the fields while generating hash should be exactly 
 1.requestURL, 2.requestType, 3.queryParams, 4.postBody,  5.headers, 6.connectionLinkName and you can ignore the fields which you don't send.

Specifying Placeholders in Invoke API

You can specify configParams, authentication details as placeholders while calling the desk invoke API. The placeholders will be replaced with the original values before sending the request to requestURL.

Supported placeholders

Placeholder	Syntax	Location(s)	Description
InstallationId	{{PROPERTY}}	requestURL, queryParams, requestHeaders	eg: https://desk.zoho.com/api/v1/installations/{{installationId}}/storage
ConfigParams	{{PROPERTY}}	requestURL, queryParams, requestHeaders	Name of Config Param eg : {{jiraAuthKey}}
resourceName	{{RESOURCETYPE.RESOURCENAME.ID}}	requestURL, queryParams, postBody, requestHeaders	Get Field eg : https://desk.zoho.com/api/v1/organizationFields/{{fields.field1.id}}
resourceName	{{RESOURCETYPE.RESOURCENAME.APINAME}}	requestURL, queryParams, postBody, requestHeaders	Set Field eg : "cf": {"{{fields.field1.apiName}}": "Testing"}

Specifying Authentication Details in Invoke API

Invoke API applies the authentication details specified while calling the API, find the below table for specifying the authentication details while calling the invoke API.

Auth Type	Where to specify ( Parameter Name )	Description
connections	payload (connectionLinkName)	Name of the connectionLinkName has to be given in the query parameter connectionLinkName while calling the invoke API.

CopiedSample of Specifying Connection in invokeAPI payload
...
requestURL         = https://api.google.com/test
connectionLinkName = googleConnection
...

#INVOKE_API_RESPONSE_OBJECT

Field	Type	Description
statusCode	integer	Status Code from the requestURL by the invoke API request.
response	string	Response from the requestURL by the invoke API request.
responseHeaders	string	Response headers sent by the requestURL.

Sample Response :

Copied{
  "responseHeaders" : {
    "Cache-Control" : "private,no-cache,no-store,max-age=0,must-revalidate",
    "Set-Cookie" : "drecn=9e1f7200-bcdf-426d-9628-79ff4e9241c8; Path=/; Secure",
    "Vary" : "Accept-Encoding",
    "Expires" : "Thu, 01 Jan 1970 00:00:00 GMT",
    "X-XSS-Protection" : "1",
    "Content-Type" : "application/json;charset=utf-8"
  },
  "response" : "{\"data\":[{\"ticketNumber\":\"176\",\"customerResponseTime\":\"2014-03-22T05:05:08.471Z\",\"productId\":null,\"contactId\":\"1892000000045028\",\"subject\":\"from forum\",\"dueDate\":\"2016-06-01T14:04:07.000Z\",\"departmentId\":\"1892000000006907\",\"channel\":\"Forums\",\"threadCount\":\"72\",\"priority\":\"High\",\"assigneeId\":\"1892000000056007\",\"closedTime\":null,\"commentCount\":\"0\",\"phone\":null,\"contact\":{\"firstName\":\"\",\"lastName\":\"as\",\"phone\":null,\"id\":\"1892000000045028\",\"type\":null,\"email\":\"manojkumar.s+4444@zohocorp.com\",\"account\":{\"website\":\"qwe.com\",\"accountName\":\"Man_Account\",\"id\":\"1892000000980421\"}},\"createdTime\":\"2014-03-06T09:49:50.000Z\",\"id\":\"1892000000094004\",\"email\":\"example@example.com\",\"status\":\"Open\"}]}",
  "statusCode" : "200"
}

Extension Data Specific APIs

The following are the APIs available to the extension that can be accessed using Desk Invoke API.

InstallationId wont be provided to the developers, instead he has to use installationId placeholder in Invoke API to call the apis.

Storage API
Configuration Param API
Log API
My Custom Permission API

Storage API

Extensions can make use of Storage API to access & modify data from the extension's DB storage. The available storage API 's are,

Add data to storage
Get data from storage
Delete data from storage

#STORAGE_DATA_OBJECT

Every storage object has the following properties.

Field	Type	Description
key	string	Key for the value which can be used to lookup.
value	JSONObject	Specifies the value that needs to be stored for the given key.
queriableValue	string	Used to group the multiple storage data. Specifies a common lookup group of the given key-value pair which will be useful for lookup from the database.

#STORAGE_DATA_OBJECT

Copied{
    "key"            : "color-red-data-id-278783",
    "queriableValue" : "color-red-datas",
    "value"          : {
        "myResult" : "Diluted solution for red color experiment 128ml "
    }
    
}

Add data to storage

Use this API to add data to the extension storage.

Add data to storage:

CopiedRequest Format:

URL             :     https://desk.zoho.com/api/v1/installedExtensions/{{installationId}}/storage
OAuth Scope     :     Desk.extensions.CREATE
RequestMethod   :     POST
RequestHeaders  :     orgId, Authorization
Content-Type    :     application/json
RequestBody     :     #STORAGE_DATA_OBJECT.
                            
                            
Response Format:

ResponseCode    : 200  
Content-Type    : application/json
Response        : #STORAGE_DATA_OBJECT

Get data from storage

Use this API to get data from the extension storage with the matching criteria.

Get data from storage:

CopiedRequest Format:

URL             :     https://desk.zoho.com/api/v1/installedExtensions/{{installationId}}/storage
OAuth Scope     :     Desk.extensions.READ
RequestMethod   :     GET
RequestHeaders  :     orgId, Authorization
QueryParams     :     key, queriableValue, from, limit
                            
                            
Response Format:

ResponseCode    : 200  
Content-Type    : application/json
Response        : JSONObject with data property
                  containing the result as array of #STORAGE_DATA_OBJECT.

Delete data from storage

Use this API to delete data from the extension storage specifying the key.

Delete data from storage:

CopiedRequest Format:

URL             :     https://desk.zoho.com/api/v1/installedExtensions/{{installationId}}/storage
OAuth Scope     :     Desk.extensions.DELETE
RequestMethod   :     DELETE
RequestHeaders  :     orgId, Authorization
QueryParams     :     key
                            
                            
Response Format:

ResponseCode    : 200

Configuration Param API

Extensions can make use of Configuration Param API to access & modify the extension's config params. The available storage API's are,

Add config params
Get config param

#CONFIG_PARAM_API_REQUEST_OBJECT

Field	Type	Description
variables	JSONArray <#CONFIG_PARAM>	Array of config params to be saved in desk

#CONFIG_PARAM_API_REQUEST_OBJECT

Copied{
  "variables" : [
    {
      "name"  : "configParam1",
      "value" : "value for the configparam 1"
    },
    {
      "name"   : "configParam3",
      "value"  : "value for the configparam 3"
    }
  ]
}

#CONFIG_PARAM

Field	Type	Description
name	string	Name of the config param
value	string	Value of the config param

#CONFIG_PARAM_API_RESPONSE_OBJECT

Copied{
  "data" : [
    {
      "defaultValue" : "default1",
      "userDefined" : true,
      "name" : "variable1",
      "options" : "[op1,  opt2]",
      "secure" : true,
      "type" : "text",
      "mandatory" : false,
      "value" : "testing",
      "varId" : "4000000011017"
    }
  ]
}

Add or update config params

Use this API to add or update config params.

Add config params:

CopiedRequest Format:

URL             :     https://desk.zoho.com/api/v1/installedExtensions/{{installationId}}/configParams
OAuth Scope     :     Desk.extensions.CREATE
RequestMethod   :     POST
RequestHeaders  :     orgId, Authorization
Content-Type    :     application/json
RequestBody     :     #CONFIG_PARAM_API_REQUEST_OBJECT.
                            
                            
Response Format:

ResponseCode    : 200  
Content-Type    : application/json
Response        : #CONFIG_PARAM_API_RESPONSE_OBJECT

Get config params

Use this API to get extension's config params.

Get config params:

CopiedRequest Format:

URL             :     https://desk.zoho.com/api/v1/installedExtensions/{{installationId}}/configParams
OAuth Scope     :     Desk.extensions.READ
RequestMethod   :     GET
RequestHeaders  :     orgId, Authorization
                            
                            
Response Format:

ResponseCode    : 200  
Content-Type    : application/json
Response        : #CONFIG_PARAM_API_RESPONSE_OBJECT

Extension Log APIs

Extensions can make use of Log API to log the extension processes. Logs can be viewed on customer's support portal.

Logs will expire after 3days.

Path to Logs:

Parent Logs List:

Sub Logs List:

During development, logs are loaded in the developer's portal.

The param - reference is a random string that is used to group multiple logs. If multiple logs are grouped using reference, the first log will be the parent log and the rest will be sub logs. Developer can group a maximum of 10 logs using a reference. Means, a parent log can have 9 sub logs as maximum.

If the logs are created without reference, they are considered as parent logs.

The available APIs for Logs are,

Add a Log

#EXTENSION_LOG_OBJECT

Field	Type	Description
reference	string	a UUID string used to group multiple logs. Logs having the same reference key will be stored as a single log.
description	string	Log message.
installationId	long	The id of the installed extension
title	string	Title of the log

Copied#EXTENSION_LOG_OBJECT
{
    "reference"      : "1d8bd6c8-5424-11e8-9c2d-fa7ae01bbebc",
    "description"    : "jira issue is created with id = 10223",
    "installationId" : "112343231355",
    "title"          : "created a jira issue"
}

#LOG_API_RESPONSE_OBJECT
{
    "parentLogId"     : "4000000022003",
    "extensionName"   : "Jira",
    "description"     : "jira issue is created with id = 10223",
    "logId"           : "4000000023001",
    "installationId"  : "112343231355",
    "title"           : "create jira issue",
    "logTime"         : "2018-05-10T07:33:13.000Z"
}

Add a Log

Use this API to add extension logs.

Add a log:

CopiedRequest Format:

URL             :     api/v1/extensionLogs
OAuth Scope     :     Desk.extensions.CREATE
RequestMethod   :     POST
RequestHeaders  :     orgId, Authorization
Content-Type    :     application/json
RequestBody     :     #EXTENSION_LOG_OBJECT.
                            
                            
Response Format:

ResponseCode    : 200  
Content-Type    : application/json
Response        : #LOG_API_RESPONSE_OBJECT

My Custom Permission API

Use this API to retrive the permission details of logged in user.

#MYPERMISSION_DATA_OBJECT

Every permission object has the following properties.

Field	Type	Description
apiName	string	apiName for the permission which can be used to lookup.
isEnabled	Boolean	Specifies whether permission is enabled or not.

#MYPERMISSION_DATA_OBJECT

Copied{
        "apiName"            : "createResolution",
        "isEnabled"          : true
        
    }

Get permission data

Use this API to get permission details of logged in user.

Get my custom permission:

CopiedRequest Format:

URL             :     https://desk.zoho.com/api/v1/installedExtensions/{{installationId}}/myCustomPermissions
OAuth Scope     :     Desk.extensions.READ
RequestMethod   :     GET
RequestHeaders  :     orgId, Authorization


Response Format:

ResponseCode    : 200  
Content-Type    : application/json
Response        : JSONObject with data property
                  containing the result as array of #MYPERMISSION_DATA_OBJECT.