Converge EMS API Guide for Common RESTful API

69 Pages·2015·0.64 MB·English

™
Converge EMS API
Guide for Common RESTful API

Software Version 1.3.0

33619 Rev. A
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API

Trademarks
All trademarks and registered trademarks are the property of their respective owners.
Copyright Notice/Restrictions
Copyright © 2015 Transition Networks. All rights reserved.
No part of this work may be reproduced or used in any form or by any means (graphic, electronic or
mechanical) without written permission from Transition Networks.
The information contained herein is confidential property of Transition Networks, Inc. The use, copying,
transfer or disclosure of such information is prohibited except by express written agreement with Transition
Networks, Inc.
Printed in the U.S.A.
Converge™ EMS API Guide for Common RESTful API Software Version 1.3.0 PN 33619 Rev. A

Contact Information
Transition Networks
10900 Red Circle Drive
Minnetonka, MN 55343 USA
Tel: [phone] or 1-800-526-9267
Fax: [phone]

Revision History
Rev Date Description
A 05/14/15 Initial release with Converge EMS API version 1.3.0.

33619 Rev. A          www.transition.com       Page 2 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API
Contents
Preface ......................................................................................................................................................... 4 
Purpose of document .............................................................................................................................. 4 
Scope ....................................................................................................................................................... 4 
Intended Audience .................................................................................................................................. 4 
Related Documents ................................................................................................................................. 4 
Device Firmware Version Requirements ................................................................................................. 4 
Glossary ....................................................................................................................................................... 6 
Converge EMS RESTful API – General Information ...................................................................................... 7 
REST Web Services Interfaces Overview .................................................................................................. 8 
Domain Object REST Web Services Interface ........................................................................................ 10 
HTTP Requests ....................................................................................................................................... 14 
HTTP Responses ..................................................................................................................................... 16 
Common RESTful Endpoints .................................................................................................................. 17 
Converge EMS REST Web Services API – Authorization Requests ............................................................ 18 
Login ...................................................................................................................................................... 18 
Logout .................................................................................................................................................... 20 
Web Login .............................................................................................................................................. 22 
Web Logout ........................................................................................................................................... 24 
Web Verify ............................................................................................................................................. 26 
Converge EMS REST Web Services API – Domain Object Requests .......................................................... 27 
Create Domain Object ........................................................................................................................... 27 
Read Domain Object .............................................................................................................................. 29 
Update Domain Object .......................................................................................................................... 33 
Delete Domain Object ........................................................................................................................... 35 
Converge EMS REST Web Services API – Meta Model Requests .............................................................. 36 
Read Meta Model Class, Fields and Validators ...................................................................................... 36 
Read All Meta Model Classes with Fields and Validators ...................................................................... 39 
Get Meta Model Hierarchy .................................................................................................................... 40 
Read Meta Model Classes (Domain Object API for Meta Model Access) .............................................. 42 
Read Meta Model Fields (Domain Object API for Meta Model Access) ................................................ 46 
Read Meta Model Field Validators (Domain Object API for Meta Model Access) ................................ 50 
Re‐discover Meta Model (Business Component API for Meta Model Discovery) ................................. 53 
Converge EMS REST Web Services Integration ......................................................................................... 55 
Converge EMS REST Web Services Integration – Message Exchange ....................................................... 56 
Alarms and Stats ........................................................................................................................................ 58 
Index .......................................................................................................................................................... 59 
Appendix A – Filter Operators ................................................................................................................... 64 

33619 Rev. A          www.transition.com       Page 3 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API
Preface

Purpose of document

This document describes the REST Web Services Interface provided by Converge EMS and
used for integration with other software applications.

Scope

The present document contains an overview of the REST Web Services Interface used by all
REST interfaces provided by Converge EMS. It also contains example of messages for
logging in and out of the application, and basic Domain Object, Meta Model, Business
Component and Documents Retrieval Commands.

Intended Audience

This document is intended for developers dedicated to creating an integration of RESTful
Web services in the context of Converge EMS.

Related Documents

Converge EMS API Guide for Common RESTful API (33619): describes the REST Web
Services Interface provided by Converge EMS and used for integration with other software
applications.

Converge EMS API Guide for Service Activation API (33620): explains how to integrate
with Converge EMS API and formulate HTTP requests for activation of services and service
components.

Converge EMS API Service Model Overview (33621): a generic document that describes
Service Inventory and Design metamodel classes and fields, and provides explanation of
service objects.

Device Firmware Version Requirements

Managed devices should be at the latest version available (e.g., S3290 v 1.9.4 or above).
33619 Rev. A          www.transition.com       Page 4 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API

Typographical Conventions

The following typographical conventions apply throughout this document:

 Commands, options, Command and options names are presented in bold type.
windows, dialogs Names of windows and dialogs also appear in bold type.
 ‘Object Names’ Object names appear in inverted commas.
 User-supplied Variable information, e.g. logins, passwords, other user-
information supplied data, appears in italic type.
 Hyperlinks Hyperlinks are presented in underlined blue type.
 Code and cmd  Fragments of code and cmd commands are presented in the
commands  Consolas font.

  Names of GUI buttons appear in square brackets and are
[ENTER] 
printed in the Consolas font.
  Guidelines which are particularly important are
Note: distinguished with a notepad and quill symbol, the blue
bold type and a ‘Note’ tag.
  Warnings for operations that may result in serious
Warning: consequences are distinguished with an exclamation mark,
the red bold type and a ‘Warning’ tag.

Useful tips are distinguished with a light bulb symbol, the

Tip: green bold type, and a ‘Tip’ tag.
33619 Rev. A          www.transition.com       Page 5 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API
Glossary
API
Application Programming Interface
CRUD
Create, Read, Update, Delete
EMS
Element Management System
GUI
Graphical User Interface
HTTP
Hypertext Transfer Protocol
NMS
Network Management System
OSS
Operations Support System
REST
Representational State Transfer
RMI
Remote Method Invocation
URL
Uniform Resource Locator
33619 Rev. A          www.transition.com       Page 6 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API
Converge EMS RESTful API – General Information
Converge EMS Application Programming Interface makes it possible for third-party entities
to integrate their applications with Converge EMS via REST Web Service Interfaces.

Converge’s API has been designed to comply with the Representational State Transfer
(REST) style recommendations, therefore the communication is mainly implemented using
the HTTP protocol, and the possible types of interactions are represented by resources and
their related operations.
33619 Rev. A          www.transition.com       Page 7 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API

REST Web Services Interfaces Overview

The general Converge EMS API architecture is presented below:

Figure 1: Converge EMS REST Web Services Interface Overview

Converge EMS provides the REST Web Services API for integration with:

This interface is used by the Converge EMS GUI to access
Domain Object API, Meta Model API, Business Component

API and Document Retrieval API.
The interface also contains the internal Converge GUI

interface used for dynamic menus.

This is the same interface as the one used for GUI without the
capability to expose the internal interface for dynamic menus.

Any OSS or Software Application can re-use this API.

Converge EMS can use the REST Web Services to invoke the API of external
applications:
33619 Rev. A          www.transition.com       Page 8 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API

This is the RESTful Domain Object Interface that can be used
for integration with external EMS/NMS and any other Software

Applications.

This interface is similar to the RESTful Domain Object API
used to integrate Converge GUI with other OSSs.

The interface can be used WITH or WITHOUT Data Mediation.

 WITHOUT MEDIATION: When used WITHOUT Data
Mediation, external EMS/NMS/devices have to support
Converge RESTful interface and Meta Model.

 WITH MEDIATION: When used WITH Data
Mediation, the interface can be mediated to any other
RESTful interface and any custom Meta Model.

The same interface is used as the RESTful Domain Object API
used to integrate with EMS/NMS.

Other interfaces, shown in blue in Figure 1 can also be provided by Converge EMS if
another type of integration is required. They can be used for tightly (e.g. Java), or loosely
(e.g. Java RMI, SNMP) coupled integration.

Note: Converge EMS also provides a framework for building new custom adapters and
extending the existing adapters, if required. Another customizability feature of Converge is
the capability to configure Mediation to external Meta Models.

For REST Web Services APIs see:
 Domain Object REST Web Services Interface
 Meta Model Object REST Web Services Interface

For REST Web Services Integration see Converge EMS™ REST W eb Services Inte gr ation .
33619 Rev. A          www.transition.com       Page 9 of 69
Transition Networks        ConvergeTM EMS API Guide for Common RESTful API

Domain Object REST Web Services Interface

External software applications can integrate with Converge EMS via the REST Web Service
Interfaces. They can use the Domain Object REST API for creation, read, update and deletion
of objects managed by Converge EMS or external, integrated Oss (EMS / NMS). Each user
role can be configured with any CRUD access per any object type.

Converge
EMS GUI

Figure 2: Converge EMS Domain Object REST Web Services Interface

Converge EMS provides the Domain Object REST Web Services API for integration
with:

This interface is used by the Converge EMS GUI to
access Domain Object API, Meta Model API, Business
Component API and Document Retrieval API.

Any OSS or software application that requires the
CRUD access to Converge EMS or external
Domain Objects (EMS / NMS / Network, etc.).
33619 Rev. A          www.transition.com       Page 10 of 69