swagger: "2.0"
|
info:
|
version: "v1"
|
title: "MTN Service Order API"
|
contact:
|
name: "MTN API Support"
|
email: "api.support@mtn.com"
|
description: The Service Order API manages the synchronization of Service Request data between the orgin and target ITSM systems.
|
host: "api.mtn.com"
|
basePath: "/ticketManagement/v1"
|
schemes:
|
- "https"
|
consumes:
|
- "application/json"
|
produces:
|
- "application/json"
|
paths:
|
'/serviceOrder':
|
post:
|
operationId: "createServiceOrder"
|
summary: "Creates a 'Service Order'"
|
description: "Creates a 'Service Order' from the orginating ITSM System to the target ITSM System."
|
tags:
|
- "serviceOrder"
|
parameters:
|
- name: "transactionId"
|
description: "Transaction ID"
|
in: "header"
|
required: true
|
type: "string"
|
- name: "body"
|
description: "Request Body"
|
in: "body"
|
required: true
|
schema:
|
$ref: "#/definitions/ServiceOrder"
|
responses:
|
'201':
|
description: "Created"
|
schema:
|
$ref: "#/definitions/ServiceOrder_Created"
|
'400':
|
description: "Bad Request"
|
schema:
|
$ref: "#/definitions/Error"
|
'401':
|
description: "Unauthorized"
|
schema:
|
$ref: "#/definitions/Error"
|
'403':
|
description: "Forbidden"
|
schema:
|
$ref: "#/definitions/Error"
|
'405':
|
description: "Method No Allowed"
|
schema:
|
$ref: "#/definitions/Error"
|
'407':
|
description: "Proxy system not authenticated"
|
schema:
|
$ref: "#/definitions/Error"
|
'409':
|
description: "Conflict"
|
schema:
|
$ref: "#/definitions/Error"
|
'500':
|
description: "Internal Server Error"
|
schema:
|
$ref: "#/definitions/Error"
|
'/serviceOrder/{id}':
|
put:
|
operationId: "updateServiceOrder"
|
summary: "Update a 'Service Order'"
|
description: "This operation updates a ServiceOrder entity entirely by Id from the orginating ITSM System to the target ITSM System in order to keep the two ITSM Systems in sync."
|
tags:
|
- "serviceOrder"
|
parameters:
|
- name: "transactionId"
|
description: "Transaction ID"
|
in: "path"
|
required: true
|
type: "string"
|
- name: "id"
|
type: "string"
|
in: "path"
|
description: "Identifier of the Service Order"
|
required: true
|
- name: "serviceOrder"
|
in: "body"
|
description: "The Service Order to be updated"
|
schema:
|
$ref: "#/definitions/ServiceOrder"
|
responses:
|
'200':
|
description: "Updated"
|
schema:
|
$ref: "#/definitions/ServiceOrder_Updated"
|
'400':
|
description: "Bad Request"
|
schema:
|
$ref: "#/definitions/Error"
|
'401':
|
description: "Unauthorized"
|
schema:
|
$ref: "#/definitions/Error"
|
'403':
|
description: "Forbidden"
|
schema:
|
$ref: "#/definitions/Error"
|
'404':
|
description: "Not Found"
|
schema:
|
$ref: "#/definitions/Error"
|
'405':
|
description: "Method No Allowed"
|
schema:
|
$ref: "#/definitions/Error"
|
'407':
|
description: "Proxy system not authenticated"
|
schema:
|
$ref: "#/definitions/Error"
|
'409':
|
description: "Conflict"
|
schema:
|
$ref: "#/definitions/Error"
|
'500':
|
description: "Internal Server Error"
|
schema:
|
$ref: "#/definitions/Error"
|
definitions:
|
ServiceOrder:
|
type: "object"
|
description: "Contains the core service order information."
|
properties:
|
category:
|
type: "string"
|
description: "Used to categorize the order, useful for the OM system, such as: APN, Static_IP."
|
description:
|
type: "string"
|
description: "A free-text description of the service order."
|
priority:
|
type: "string"
|
description: "Can be used by consumers to prioritize orders in a Service Order Management system."
|
originSystem:
|
type: "string"
|
description: "System originating the request."
|
note:
|
type: "array"
|
description: "Extra-information about the order; e.g. useful to add extra delivery information that could be useful for a human process."
|
items:
|
$ref: "#/definitions/Note"
|
attachment:
|
type: "array"
|
description: "Complements the description of an element (for instance a product) through video, pictures."
|
items:
|
$ref: "#/definitions/Attachment"
|
orderItem:
|
type: "array"
|
description: "A list of service order items to be processed by this order."
|
items:
|
$ref: "#/definitions/OrderItem"
|
Note:
|
required:
|
- "type"
|
type: "object"
|
description: "Extra information about a given entity."
|
properties:
|
type:
|
type: "string"
|
description: "Type of the note."
|
example: "comment"
|
enum:
|
- "comment"
|
- "workNote"
|
text:
|
type: "string"
|
description: "The text of the note."
|
example: "This is a comment and viewable by the customer."
|
Attachment:
|
type: "object"
|
description: "Complements the description of an element (for instance a product) through video, pictures."
|
properties:
|
name:
|
type: "string"
|
description: "Name of the attachment."
|
example: "Screenshot.jpg"
|
description:
|
type: "string"
|
description: "The description of the attachment."
|
example: "Screenshot of the service request."
|
attachment:
|
type: "string"
|
description: "The attachment codified in Base64."
|
OrderItem:
|
type: "object"
|
properties:
|
type:
|
type: "string"
|
description: "Type of key value pairs for the variables."
|
example: "targetSystem"
|
text:
|
type: "string"
|
description: "the key value of the variable type."
|
example: "ServiceNow"
|
Error:
|
type: "object"
|
required:
|
- code
|
- reason
|
description: "Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)."
|
properties:
|
timeStamp:
|
type: "string"
|
format: "date-time"
|
description: "Timestamp when the error occured."
|
example: "2018-05-01T00:00"
|
status:
|
type: "integer"
|
description: "HTTP Error code extension."
|
error:
|
type: "string"
|
description: "Details the error."
|
message:
|
type: "string"
|
description: "More details and corrective actions related to the error which can be shown to a client user."
|
path:
|
type: "string"
|
description: "The path of the error."
|
ServiceOrder_Created:
|
type: "object"
|
required:
|
- id
|
- href
|
description: "Used when a new Service Order is created."
|
properties:
|
id:
|
type: "integer"
|
description: "ID created on repository side."
|
example: "12345"
|
data:
|
type: "object"
|
description: "The related information generated as received by the target system."
|
properties:
|
statusCode:
|
type: "string"
|
description: "Status Code from target system to indicate transaction status of Service Order creation."
|
example: "0"
|
message:
|
type: "string"
|
description: "Additional information to the status response of creation of the Service Order."
|
example: "Action succesfully processed."
|
_links:
|
type: "object"
|
description: "Relevant links to the service order."
|
properties:
|
self:
|
type: "object"
|
properties:
|
href:
|
type: "string"
|
description: "Hyperlink to access the order."
|
example: "https://host:port/ticketManagement/v1/serviceOrder/12345"
|
ServiceOrder_Updated:
|
type: "object"
|
required:
|
- id
|
- href
|
description: "Used when a Service Order is updated."
|
properties:
|
id:
|
type: "integer"
|
description: "ID updated on repository side."
|
example: "12345"
|
data:
|
type: "object"
|
description: "The related information generated as received by the target system."
|
properties:
|
statusCode:
|
type: "string"
|
description: "Status Code from target system to indicate transaction status of Service Order update."
|
example: "0"
|
message:
|
type: "string"
|
description: "Additional information to the status response of updating of the Service Order."
|
example: "Action succesfully processed."
|
_links:
|
type: "object"
|
description: "Relevant links to the service order."
|
properties:
|
self:
|
type: "object"
|
properties:
|
href:
|
type: "string"
|
description: "Hyperlink to access the order."
|
example: "https://host:port/ticketManagement/v1/serviceOrder/12345"
|
|
