A

Overview

An API (Application Programming Interface) is a set of rules that allow programs to interact with each other. One such rule allows you to get a piece of information (resource) when you link to a specific URL or retrieve ticket information via a smart phone or a third party service. Each URL is a 'request' and the data sent back to you is known as a 'response'.

The Intelligent Service Management (ISM) Web Services allows you to encode your calls using REST (Representational State Transfer) API. REST is an architectural style that defines how applications communicate over HTTP (Hypertext Transfer Protocol). It is usually associated with exchanging JSON (JavaScript Object Notation) and XML (Extensible Markup Language) documents between a client and a server. To learn more about REST APIs, refer to REST API basics.

As an administrator you can validate the information using Swagger to create, update, and delete resources. Swagger is a commonly used web application to document APIs. With Swagger Serviceaide has built a simple way for developers to understand this API. In this article, we will guide you through an example for the methods related to creating, updating, and deleting an incident and how the method responds to requests.

The following HTTP methods are used in REST APIs. Use:

• GET to retrieve a resource from a server.
• POST to create a new resource on a server.
• PUT to edit or update a resource on a server, which can be an object or file.
• DELETE to remove a resource from a server.

Status Codes/Response Code

It is important for client applications to manage HTTP status codes correctly. Status codes convey the results of your request. The following status code applies to the REST API. 

How to Use Swagger

You can access Swagger using the ISM environment followed by the swagger URL as follows: https://<datacenter>.serviceaide.com/csmconnector/swagger-ui.html 

Here are the Staging environment URLs

• CSMStaging: https://csmstaging.serviceaide.com/csmconnector/swagger-ui.html
• CSM2Staging: https://csm2staging.serviceaide.com/csmconnector/swagger-ui.html
• CSM5Staging: https://csm5staging.serviceaide.com/csmconnector/swagger-ui.html

Here are the Production environment URLs

• CSM2: https://csm2.serviceaide.com/csmconnector/swagger-ui.html
• CSM3: https://csm3.serviceaide.com/csmconnector/swagger-ui.html
• CSM5: https://csm5.serviceaide.com/csmconnector/swagger-ui.html

Prerequisites

Any user who has the following information can use the REST API to create, update, and delete resources.:

• ISM app URL.
• AuthToken: auth token can only be accessed through the API user. AuthToken is required to authenticate the API user's request.
  Note: API user is created solely for the purpose of integration. To create an API user, you must contact Serviceaide Support. There is one API user for each slice. 
• Slice token
• Web service username
• Web service user password

How to Access AuthToken 

To copy AuthToken, perform the following steps:

1. On the Manage menu, click Tools and then Users.
2. Select the Filter tab and select System Users from the By Type group.
3. Click Apply to view the API User in the list.
4. Click to edit properties. The API User page is displayed.
5. Copy the AuthToken from the Basic Information section in the API User page.
   

How to Access Slice Token

To copy slice token, perform the following steps:

1. On the Manage menu, click Tools and then Slice Configuration. The Slice Configuration page is displayed.
2. Copy the slice token by clicking the General Information tab.

GET Method - Incident 

While retrieving a record such as incident, from a server, you can learn how APIs use HTTP methods and Response codes to differentiate operations and results. The following example describes how you can retrieve the existing incidents record.:

1. Click GET or Expand Operations to retrieve information.
   
   
2. Specify the following details in the Parameters section.:
     - ISM application URL
     - User authtoken
     - Slice token
     - Web service user name and password
3. Click Try it out. You will get the response as follows.

Response

After the GET request is executed, a response is received in the following format as specified below.

POST Method- Incident

You can use a POST method to create a new resource such as incident, request, and so on. The following example describes how you can create a new incident.

1. Click POST to create information.
   
   
2. Specify the following details in the Parameters section.:
     - ISM application URL
     - User authtoken
     - Slice token
     - Web service user name and password
3. Click the Example Value text box. The operations displayed in the text box will be copied to the Incident text box.
4. Click Try it out. You will get the response as follows.

Valid Ticket Attributes

The following information is displayed in the Example Value box. This is applicable to all the ticket types.

Sample for Assigning a Ticket Using REST

{

"TicketIdentifier":"200-2",

"AssignedContactUserName":"AnalystUsername",

"AssignedGroup":"Administration"

}

Sample for Adding a worklog and send email to the recipients (testuser@acme.com and test@acme.com) using REST

{

"TicketIdentifier":"200-3","communicationSendCC":"test@acme.com",

"communicationSendTo":"testuser@acme.com",

"ClientViewable":"1",

"sendMail":"1",

"WorklogTypeCode":"1",

"Text":"The
ticket has been fixed, validate and revert"

}

Response

After the POST request is executed, a response is received in the following format as specified below.

Sample 

GET Method - Incident/{id}

You can use this method to retrieve a specific incident details by specifying the ID. The following example describes how you can get details of a specific incident.:

1. Click GET to retrieve a specific incident information.
   
   
2. Specify the following details in the Parameters section.:
     - ISM application URL
     - User authtoken
     - Slice token
     - Web service user name and password
     - Specify the incident ID for which you want to retrieve information.
3. Click Try it out. You will get the response as follows.
   
   

Now, you can validate the response code using the Status code/Response Code section in this article.

REST API Catalog

This the list of web services wrapper interface to enable access to the existing Intelligent Service Management (ISM) article contains functionality that is exposed through the Rest web services API.