About REST API
Representational State Transfer (REST) has similar functionality as that of Servlet API except for a few distinctness [Refer Different between Servlet and REST API to know more]. The REST API is completely automated, and users need not log into ServiceDesk Plus to perform operations. The purpose of REST API can be explained with the help of a scenario.
Let's take the case of a network monitoring tool (external application) that is installed in your network. In general, when an alarm is raised by the network monitoring tool, an e-mail notification is sent as a ticket to ServiceDesk Plus application. The field values (priority, level, impact, category and so on) should be filled by the technician manually in ServiceDesk Plus. This mechanism is time consuming and eventually results as a dip in your helpdesk productivity chart.
With REST API, you can automate this ticketing process. When an alarm is triggered, the network monitoring tool provides the field details and raises a ticket automatically in ServiceDesk Plus via http protocol. The ticket ID is sent back to the network monitoring tool in order to perform any further operations over the request.
When the cause for the alarm is resolved, ServiceDesk Plus will invoke an URL (callback URL) that was provided by the monitoring tool. The URL functions as a notification to the external application indicating that the ticket is resolved. If this URL (callback URL) is not provided, ServiceDesk Plus will not perform any additional operation on the ticket. When ServiceDesk Plus invokes the callback URL, the network monitoring tool can perform "any" internal operations based on the URL invocation. However, the expectation is that the application will clear the alarm (which was raised as a ticket) at their end.
Note: Please note that the callback URL is applicable only while creating and editing requests.
The operations performed with REST API are based on the 'operation' parameter and is sent to the url via HTTP POST method. The url format is as shown below,
Authentication to the ServiceDesk Plus application is key based i.e., an API key is sent along with the url for every operation. This key is technician based and can be generate for technicians with login privilege. The role given to the technician is also taken into consideration, so the key is valid only for the role given to the technician. Once the key is generated, the key is manually transferred to the integrated application so that the application can use the key for further API operations. If the key is invalid (key is expired or the technician login is disabled), the operation fails and an error is propagated to the integrated application.
1. Please note that the administrator alone has the privilege to generate the authentication key for technicians with login permission.
2. If a login for the technician is disabled, then the technician key is deleted.
3. The operations can be performed based on the Role provided to the technician.
Currently, XML is the supported input and output format. The input data is sent as an XML string along with the technician key and operation name, while the output is exposed as an XML string.
Generating API Key
The authentication between ServiceDesk Plus and integrated application is through an API key. A unique key is generated for a technician with login permission in ServiceDesk Plus application.
Click Admin -> Technicians icon under User block.
If you want to generate the API key to the existing
technician, click the edit icon
beside the technician.
If you want to generate the API key to a new technician, click Add New Technician link, enter the technician details and provide login permission.
link under the API key details block. You can select a time frame
for the key to expire using the calendar icon or simply
retain the same key perpetually.
If a key is already generated for the technician, a Re-generate link appears.
The key in the above image is generated for an existing technician. A time frame for the key is selected which shows the date, month, year and the time (in hours and minutes) when the key will expire.
REST API supported operations
The REST API supports only request related operations which can be separated into:-
Operations on request: adding new request
Operations on a specific request:
editing, closing, deleting and viewing existing requests.
adding new notes to a request, editing, deleting and viewing existing notes.
adding worklog to a request, editing, deleting and viewing existing worklogs.