DeskDirector API

DeskDirector provide a set of generic APIs and platform APIs for you to integrate with. It allows you to trigger workflow based on webhook, such as change status of ticket, add ticket note on behalf of user or modify permissions through admin API.

In this article, we will go through what is available and the authorization system.

API Versions

  • API v1 APIs under these category has been deprecated. It is used in our legacy system. We do not recommend to use them and we do not provide any support against it. All JSON properties been serialized as Pascal case.
  • API v2 Those APIs are new generation of APIs, it is using camel case inside JSON response. It is solid and well supported API. They have been used under all our existing systems.
  • API v3 V3 has been created recently, the purpose of v3 is for new admin console. Where legacy admin console uses API v1 and v2, the model of old API for admin console is not easy to consume. Thus we created v3 branch for new API contracts on admin related API.

API category

  • Public API - or generic API, those APIs are served as a way to retrieve information. In general it is used to retrieve information.
  • Admin API - it is used for admin console. We have recently allowed API key to used against admin related API. API Key's role is equivalent to admin role.
  • Portal API - it is used by portal.
  • TECH API - it is used by TECH.

The way to consume API

Access Token

Portal and TECH can generate access token. Each access token will be available for 60 min. They have been appended to our new dynamic system to allow custom page to verify given user or query against DeskDirector API on behalf of user.

Our dynamic menu inside portal will allow use of access token. On end user click on dynamic menu, system will append access token to given website. That website can use these token to verify user's identity and display content based on that.

To use access token, you need to put it inside authorization header of HTTP request. Below is example of authorization header. Please replace {access_token} with the actual token.

Authorization: DdAccessToken {access_token}

API Key

API Key can be generated under https://{deskdirector site host}/admin/ddapi/. It can used against public API or admin related API.

To use it, you need to put it inside authorization header. Below is example of authorization header, please replace {api_key} with the actual key.

Authorization: DdApi {api_key}

Cookie

Cookie can be used against related platform. End user's cookie can use against portal API, member cookie can use against TECH API or admin API if he has previlage.

SwaggerUI

You can discover and access API definition by access swagger UI from following address.

https://{deskdirector site host}/swagger

At top of swagger UI page, you can select different version. Keep in mind, even though Swagger showing service model as pascal case, for API v2 and v3, it is actually camel case.

How to update entity

DeskDirector API provide many API to create entity, we also have API to update entity. In many case, we use put to update all relavant properties. Currently, only TECH's update ticket API supports patch operation. Please test them throughly before put it into production.


How did we do?