Overview
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 (incident, change request, and so on) from a server. Swagger is a commonly used web application to document APIs. 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.
| Status Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 204 | No content |
| 400 | Bad request |
| 403 | Forbidden |
| 404 | Not found |
| 500 | Internal server error |
Prerequisites
Any user who has the following information can use REST API to create, update, and delete resources.:
- ISM (earlier CSM) 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
to edit properties. The API User page is displayed. - Copy the AuthToken from the Basic Information section in the API User page.
Note
Each tenant is entitled to one API user only if they want to integrate REST API with ISM.
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 - Retrieving a Resource
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.
- 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.
POST Method- Create a Resource
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.
- 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.
The following information is displayed in the Example Value box.
Code Block- Incident Value Valid Ticket Attributes { |
|---|
Response
After the POST request is executed, a response is received in the following format as specified below.
GET Method - Retrieve Resource 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.
- 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.
Add Comment