ITSM API
BASICS
Mahjar Asgariannoor |
Channel Care
Agenda • What is a Rest-API?
• How to generate your Token
• Find API Endpoints in ESM
• Getting started with Postman &
Powershell
• Three examples with or without a body
2
REST-API
Application Programming Interface
An Interface used to exchange data between applications and let them
communicate with each other
Representational State Transfer
REST communication between web based applications
There are public and private APIs . Public APIs are officially supported and
protected against sudden changes.
We do not recommend using private APIs for customizing because we as the
software manufacturer reserve the right to make changes to them at any time.
Sometimes even without announcing it!
Public API Endpoints are recognizable with this marker
3
Get your
API Token
1. Go to Administration ➡
Integration ➡Web Service Tokens
2. Choose a Name, expiration date
and which user it is bound to
(choose wisely!!) (Left picture) and
click generate API token
3. Copy the API token and store it.
If you click close without saving
your token, you wont be ableto
see it again! (Right picture)
4
Contents of an API request
• An Endpoint ➡ [Link]
• A header. It contains meta information e.g. an API Token for authentication
• The operation (GET, POST, PUT or DELETE)
• A body {item1: value 1, item2: value2 […] itemN: valueN}. Some endpoints do not
require one
Header
Body
⬆ ⬆
5
Operatio
Endpoi n
API endpoints in
ESM
Navigate to Integration
1: Endpoint Name ➡ Web
Services
2: Required operation
3: Indicates whether endpoint is
public or not
4: Endpoint Link. Required
parameters are written in curly
brackets
5: Description, Documentation if
available
6: Required parameters and
their type to use this endpoint
7: What this endpoint will
return if you use it. Can be
empty. In this example: ID of
your new object 6
8: A code example you can
Getting started
with Postman Download
Create a new collection. Under variables you
are able to setup variables which you can use
for every API request in your collection. Add a
new request.
1. Fill in your endpoint link and select
the operation. Under params you can fill
in your parameters
2. Select the proper authorization
method. The value should contain your
RAW-Token
3. Under Body, fill in the body of your
request
4. You will see the response area at the
bottom area of Postman. Sometimes you
get a return statement as shown here. 7
Be aware of the status code.
Using Postman API request in
Powershell
• If you want to use your API request you
built in Postman in Powershell, you can
use the code snippet function. Select
Powershell – RestMethod and then you
can copy the code into Powershell
8
Example 1: Change a ticket
We want to make changes to ticket TCK00026 and change Initiator, Subject
and Summary
9
1. First we want to extract the ID of our Ticket TCK00026 using the fragments
endpoint. We use the filter in (1) and mention every column we need in (2).
Since we only want the ID of our ticket, we only mention it and nothing else.
2. We store the ticket ID in a variable (3)
3. We use this ID to fill our body in (4) we have to provide the ID there so the
API endpoint can identify which activity we want to change.
4. We send our request with the correct method, headers and body in (5)
10
Example 2: Export contract attachments
• ESM uses two different APIs for
downloading attachments:
1 Attachment: Filestorage
2 or more attachments:
commonstorage (they will be
packed into a zip archive)
You can test this by pressing F12
and switch to “Network” right
before you download 2+
attachments:
Under payload you can find an
array with all FileIDs that you have
selected
11
Example 2: Export contract attachments
12
Example 3: Close tickets
Prior to example 1: Fill in the body with the EOIDs of every ticket you want to close (not
the FID!)
The documentation tells you exactly which values you need for Reason and ErrorType
13
THANK
YOU
Sources used:
REST-API Basics in German
Web Services: REST API integration
Fragments Data Service: Update fragment
API Basics: A Beginner’s Guide to APIs | Postman Blog