A

Table of Contents

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.

...

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

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:

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

Info

title	Note

Each Slice is entitled to one API user for using the REST API

How to Access Slice Token

To copy slice token, perform the following steps:

On the Manage menu, click Tools and then Slice Configuration. The Slice Configuration page is displayed.
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.:

Click GET or Expand Operations to retrieve information.
Image Removed
Specify the following details in the Parameters section.:
- ISM application URL
- User authtoken
- Slice token
- Web service user name and password
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.

Image Removed

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.

Click POST to create information.
Image Removed
Specify the following details in the Parameters section.:
- ISM application URL
- User authtoken
- Slice token
- Web service user name and password
Click the Example Value text box. The operations displayed in the text box will be copied to the Incident text box.
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

Code Block
{ "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

Code Block

{

"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.

Image Removed

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.:

Click GET to retrieve a specific incident information.
Image Removed
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.
Click Try it out. You will get the response as follows.
Image Removed

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

Table of Contents