From 37a75d490903539995e67aa2cebe209d1c5b3e6f Mon Sep 17 00:00:00 2001 From: timschaeren Date: Tue, 3 Sep 2024 13:27:28 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20swisspos?= =?UTF-8?q?t/myit-api-doc@f86305bd016b27cc2f3a84a66557d9adfacd4f95=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- incidentRestAPI.html | 924 ++++++++++++++++++++++--------------------- incidentRestAPI.yml | 9 +- 2 files changed, 470 insertions(+), 463 deletions(-) diff --git a/incidentRestAPI.html b/incidentRestAPI.html index 8945c2e..65730dc 100644 --- a/incidentRestAPI.html +++ b/incidentRestAPI.html @@ -13,356 +13,356 @@ margin: 0; } - -
API docs by Redocly
API docs by Redocly

Incident REST API (1.0.0)

Download OpenAPI specification:Download

handles communication between the MyIT incident system and partner systems.

-

create a new incident

creates a new incident in myIT and returns said incident.

-
Authorizations:
BasicAuth
Request Body schema: application/json

The values to intially write to the incident.

-
partnerId
required
string

the id of the partner system, agreed upon with the MyIT team.

-
partnerIncidentId
required
string

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

-
description
required
string

the descriptive title of the incident.

-
short_description
required
string

the description of the incident, describing the situation in detail.

-
location
string

the name or sys-id of the concerned location. If you don't know what to put here, please ask your swisspost contact.

-
assignment_group
string

the name or sys-id of the assignment_group this incident should be assigned to. If you don't know what to put here, please ask your swisspost contact.

-
cmdb_ci
string

the name or sys-id of the concerned configuration item. If you don't know what to put here, please ask your swisspost contact.

-
causing_ci
required
string

the name or sys-id of the underlying causing configuration item. If you don't know what to put here, please ask your swisspost contact.

-
Array of objects

any attachments you'd like to add to the incident. The content must be base64 encoded.

-

Responses

Request samples

Content type
application/json
{
  • "partnerId": "SystemX",
  • "partnerIncidentId": "1234567890",
  • "description": "Some problem with something",
  • "short_description": "There is a complicated problem with the incident rest api - HELP!",
  • "location": "afeeadcb8776c6103efc00000000",
  • "assignment_group": "DEVOPS-MYIT",
  • "cmdb_ci": "w010xq",
  • "causing_ci": "w010xq",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 00000000000000000000000000000001 created.",
  • "data": {
    }
}

fetch an existing incident

Requires 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' and returns the corresponding incident.

-
Authorizations:
BasicAuth
query Parameters
partnerId
required
string
Example: partnerId=SystemX

The id of the partner system, to be agreed upon with the MyIT team.

-
incidentId
required
string
Example: incidentId=6d101e0487e3ca903ef00000000000

The MyIT-internal id of the incident.

-
partnerIncidentId
required
string
Example: partnerIncidentId=1234567890

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

-

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": {
    }
}

update an incident

updates an incident that already exists in myIT. 'partnerId' AND 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params.

-
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
required
string

the id of the partner system, agreed upon with the MyIT team.

-
incidentId
required
string

The MyIT-internal id of the incident.

-
partnerIncidentId
required
string

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

-
short_description
string

example field to update

-

Responses

Request samples

Content type
application/json
{
  • "partnerId": "SystemX",
  • "incidentId": "43c569a98771f5106dc8630000000000",
  • "partnerIncidentId": "1234567890",
  • "short_description": "this is an updated description of the problem"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 43c569a98771f5106dc8630000000000 updated.",
  • "data": {
    }
}

add attachments

adds attachments to an incident that already exists in myIT. 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params. Any attachments must be base64 encoded.

-
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
string

the id of the partner system, agreed upon with the MyIT team.

-
incidentId
string

The MyIT-internal id of the incident.

-
partnerIncidentId
string

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

-
Array of objects

any attachments you'd like to add to the incident. The content must be base64 encoded.

-

Responses

Request samples

Content type
application/json
{
  • "partnerId": "SystemX",
  • "incidentId": "6d101e0487e3ca903ef00000000000",
  • "partnerIncidentId": "1234567890",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Attachment(s) added to Incident 43c569a98771f5106dc8630000000000.",
  • "data": {
    }
}

add a worknote

adds a worknote to an incident that already exists in myIT. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

-
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
string
incidentId
string
partnerIncidentId
string
worknote
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "worknote": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Worknote added to incident 43c569a98771f5106dc8630000000000.",
  • "data": {
    }
}

add a comment

adds a comment to an incident that already exists in myIT. 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params.

-
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
string
incidentId
string
partnerIncidentId
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Comment added to incident 43c569a98771f5106dc8630000000000.",
  • "data": {
    }
}

resolve an incident

resolves an incident in myIT. Requires a worknote. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

-
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
required
string
incidentId
required
string
partnerIncidentId
required
string
worknote
required
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "worknote": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 43c569a98771f5106dc8630000000000 resolved.",
  • "data": {
    }
}

reopen an incident

Reopens an incident in myIT that has status 'resolved'. Requires a worknote. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

-
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
required
string
incidentId
required
string
partnerIncidentId
required
string
worknote
required
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "worknote": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 43c569a98771f5106dc8630000000000 reopened.",
  • "data": {
    }
}

Notification via POST request

Sends a POST request to the partner's callback URL when an incident changes containing the complete incident.

-
Authorizations:
BasicAuth
Request Body schema: application/json

The incident data sent to the callback URL.

-
metaData
string
number
string
time_worked
string
short_description
string
priority
number
severity
number
opened_at
string
category
string
incident_id
string
class
string

Responses

Request samples

Content type
application/json
{
  • "metaData": "The incident has changed. This is the newest state:",
  • "number": "INC0000001",
  • "time_worked": "1970-01-01 01:54:46",
  • "short_description": "update",
  • "priority": 1,
  • "severity": 2,
  • "opened_at": "2023-11-23T09:16:47Z",
  • "category": "service_request",
  • "incident_id": "f806607f87a6f9d03efcec0000000000",
  • "class": "incident"
}

Notification via GET request

Sends a GET request to the partner's callback URL with incidentId and callbackUrl as query parameters when an incident changes. This URL can be queried with GET to then receive the changed incident.

-
Authorizations:
BasicAuth
query Parameters
incidentId
string
Example: incidentId=f806607f87a6f9d03efcec0000000000

The ID of the incident that changed.

-
callbackUrl
string
Example: callbackUrl=https://<MyIT-url>/api/x_ssagd_inc_rest/rest/incident?partnerId=systemX&incidentId=f806607f87a6f9d03efcec0000000000

The readymade URL leading to the changed incident.

-

Responses

+ " fill="currentColor">

Incident REST API (1.0.0)

Download OpenAPI specification:Download

handles communication between the MyIT incident system and partner systems.

+

create a new incident

creates a new incident in myIT and returns said incident.

+
Authorizations:
BasicAuth
Request Body schema: application/json

The values to intially write to the incident.

+
partnerId
required
string

the id of the partner system, agreed upon with the MyIT team.

+
partnerIncidentId
required
string

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

+
channel
required
string

possible values are 'monitoring' or 'vendor'. If you are an external vendor, please choose 'vendor'. If you are an internal event-monitoring system, please choose 'monitoring'.

+
description
required
string

the descriptive title of the incident.

+
short_description
required
string

the description of the incident, describing the situation in detail.

+
location
string

the name or sys-id of the concerned location. If you don't know what to put here, please ask your swisspost contact.

+
assignment_group
string

the name or sys-id of the assignment_group this incident should be assigned to. If you don't know what to put here, please ask your swisspost contact.

+
cmdb_ci
string

the name or sys-id of the concerned configuration item. If you don't know what to put here, please ask your swisspost contact.

+
causing_ci
string

the name or sys-id of the underlying causing configuration item. If you don't know what to put here, please ask your swisspost contact. This is mandatory only for systems of channel 'monitoring'.

+
Array of objects

any attachments you'd like to add to the incident. The content must be base64 encoded.

+

Responses

Request samples

Content type
application/json
{
  • "partnerId": "SystemX",
  • "partnerIncidentId": "1234567890",
  • "channel": "vendor",
  • "description": "Some problem with something",
  • "short_description": "There is a complicated problem with the incident rest api - HELP!",
  • "location": "afeeadcb8776c6103efc00000000",
  • "assignment_group": "DEVOPS-MYIT",
  • "cmdb_ci": "w010xq",
  • "causing_ci": "w010xq",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 00000000000000000000000000000001 created.",
  • "data": {
    }
}

fetch an existing incident

Requires 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' and returns the corresponding incident.

+
Authorizations:
BasicAuth
query Parameters
partnerId
required
string
Example: partnerId=SystemX

The id of the partner system, to be agreed upon with the MyIT team.

+
incidentId
required
string
Example: incidentId=6d101e0487e3ca903ef00000000000

The MyIT-internal id of the incident.

+
partnerIncidentId
required
string
Example: partnerIncidentId=1234567890

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

+

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "data": {
    }
}

update an incident

updates an incident that already exists in myIT. 'partnerId' AND 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params.

+
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
required
string

the id of the partner system, agreed upon with the MyIT team.

+
incidentId
required
string

The MyIT-internal id of the incident.

+
partnerIncidentId
required
string

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

+
short_description
string

example field to update

+

Responses

Request samples

Content type
application/json
{
  • "partnerId": "SystemX",
  • "incidentId": "43c569a98771f5106dc8630000000000",
  • "partnerIncidentId": "1234567890",
  • "short_description": "this is an updated description of the problem"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 43c569a98771f5106dc8630000000000 updated.",
  • "data": {
    }
}

add attachments

adds attachments to an incident that already exists in myIT. 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params. Any attachments must be base64 encoded.

+
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
string

the id of the partner system, agreed upon with the MyIT team.

+
incidentId
string

The MyIT-internal id of the incident.

+
partnerIncidentId
string

your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again.

+
Array of objects

any attachments you'd like to add to the incident. The content must be base64 encoded.

+

Responses

Request samples

Content type
application/json
{
  • "partnerId": "SystemX",
  • "incidentId": "6d101e0487e3ca903ef00000000000",
  • "partnerIncidentId": "1234567890",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Attachment(s) added to Incident 43c569a98771f5106dc8630000000000.",
  • "data": {
    }
}

add a worknote

adds a worknote to an incident that already exists in myIT. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

+
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
string
incidentId
string
partnerIncidentId
string
worknote
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "worknote": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Worknote added to incident 43c569a98771f5106dc8630000000000.",
  • "data": {
    }
}

add a comment

adds a comment to an incident that already exists in myIT. 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params.

+
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
string
incidentId
string
partnerIncidentId
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Comment added to incident 43c569a98771f5106dc8630000000000.",
  • "data": {
    }
}

resolve an incident

resolves an incident in myIT. Requires a worknote. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

+
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
required
string
incidentId
required
string
partnerIncidentId
required
string
worknote
required
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "worknote": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 43c569a98771f5106dc8630000000000 resolved.",
  • "data": {
    }
}

reopen an incident

Reopens an incident in myIT that has status 'resolved'. Requires a worknote. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

+
Authorizations:
BasicAuth
Request Body schema: application/json
partnerId
required
string
incidentId
required
string
partnerIncidentId
required
string
worknote
required
string

Responses

Request samples

Content type
application/json
{
  • "partnerId": "string",
  • "incidentId": "string",
  • "partnerIncidentId": "string",
  • "worknote": "string"
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "message": "Incident 43c569a98771f5106dc8630000000000 reopened.",
  • "data": {
    }
}

Notification via POST request

Sends a POST request to the partner's callback URL when an incident changes containing the complete incident.

+
Authorizations:
BasicAuth
Request Body schema: application/json

The incident data sent to the callback URL.

+
metaData
string
number
string
time_worked
string
short_description
string
priority
number
severity
number
opened_at
string
category
string
incident_id
string
class
string

Responses

Request samples

Content type
application/json
{
  • "metaData": "The incident has changed. This is the newest state:",
  • "number": "INC0000001",
  • "time_worked": "1970-01-01 01:54:46",
  • "short_description": "update",
  • "priority": 1,
  • "severity": 2,
  • "opened_at": "2023-11-23T09:16:47Z",
  • "category": "service_request",
  • "incident_id": "f806607f87a6f9d03efcec0000000000",
  • "class": "incident"
}

Notification via GET request

Sends a GET request to the partner's callback URL with incidentId and callbackUrl as query parameters when an incident changes. This URL can be queried with GET to then receive the changed incident.

+
Authorizations:
BasicAuth
query Parameters
incidentId
string
Example: incidentId=f806607f87a6f9d03efcec0000000000

The ID of the incident that changed.

+
callbackUrl
string
Example: callbackUrl=https://<MyIT-url>/api/x_ssagd_inc_rest/rest/incident?partnerId=systemX&incidentId=f806607f87a6f9d03efcec0000000000

The readymade URL leading to the changed incident.

+

Responses