Upload
dongoc
View
224
Download
0
Embed Size (px)
Citation preview
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
33619 Rev. A www.transition.com Page 2 of 69
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: 952- 941-7600 or 1-800-526-9267 Fax: 952-941-2322
Revision History
Rev Date Description
A 05/14/15 Initial release with Converge EMS API version 1.3.0.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 3 of 69
ContentsPreface ......................................................................................................................................................... 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
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 4 of 69
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).
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 5 of 69
Typographical Conventions
The following typographical conventions apply throughout this document:
Commands, options, windows, dialogs
Command and options names are presented in bold type. Names of windows and dialogs also appear in bold type.
‘Object Names’ Object names appear in inverted commas.
User-supplied information
Variable information, e.g. logins, passwords, other user- supplied data, appears in italic type.
Hyperlinks Hyperlinks are presented in underlined blue type.
Code and cmd
commands
Fragments of code and cmd commands are presented in the Consolas font.
[ENTER] Names of GUI buttons appear in square brackets and are
printed in the Consolas font.
Note:
Guidelines which are particularly important are distinguished with a notepad and quill symbol, the blue bold type and a ‘Note’ tag.
Warning:
Warnings for operations that may result in serious consequences are distinguished with an exclamation mark, the red bold type and a ‘Warning’ tag.
Tip:
Useful tips are distinguished with a light bulb symbol, the
green bold type, and a ‘Tip’ tag.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 6 of 69
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
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 7 of 69
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.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 8 of 69
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:
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 9 of 69
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 .
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 10 of 69
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.).
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 11 of 69
Meta Model Object REST Web Services Interface
External software applications can integrate with Converge EMS via the REST Web Service Interfaces.
They can use the Meta Model REST API for reading Meta Model used by Converge EMS.
They can use the Domain Object REST API for reading the Meta Model Classes, Meta Model Fields and Meta Model Validators as Domain Objects.
They can use the Business Component API for initiating re-discovery of the Meta Model.
Converge EMS GUI
Figure 3: Converge EMS Meta Model 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 access to Converge EMS Meta Model.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 12 of 69
Converge EMS REST Web Services API – Message Exchange
The following sequence diagram shows the message exchange between the Converge EMS GUI / OSS and Converge EMS.
Figure 4: Converge EMS REST Web Services API Message Exchange Matrix
The message exchange matrix consists of the following REQUEST / RESPONSE messages, where Login and Logout must be first and last, respectively, and the remaining transactions can be executed in any order (if at all).
Request Name Request Description Request Elements Response Elements
Login Logging in to interface http(s) request, PUT, http(s) response, status
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 13 of 69
Note: This can be replaced with a Web Login to provide for a web browser login via a web form.
URI, credentials token
Meta Model API Reading Meta Model
See also Meta Model Object REST Web Services Interface
http(s) request, GET, URI, authorization
()
Domain Object
API
Creation, Reading, Updating, and Deleting Domain Objects (CRUD)
http(s) request, GET / PUT / POST / DELETE, URI, authorization
()
Business
Component API
Invocation of Business Component methods
http(s) request, POST, URI, authorization
()
Document
Retrieval API
Retrieving documents http(s) request, GET, URI, authorization
Logout Logging out of interface
Note: This can be replaced with a Web Logout to provide for a web browser logout via a web form.
http(s) request, DELETE, URI, token
http(s) response, status
Table 1: Converge EMS REST Web Services API Message Exchange Matrix
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 14 of 69
HTTP Requests
As a result of the assumed communication architecture, the following are the requirements for the HTTP messages sent to Converge EMS over the REST Web Services API:
Element Requirement
HTTP Message Type Request (mandatory)
HTTP Message must contain a header (the content of which depends on the endpoint and the method)
may contain a message body (only for some endpoints and methods)
HTTP Version HTTP/1.1
HTTP Methods GET – retrieves or read a representation of a resource in XML or JSON; the desired Status Code for this operation is 200 (OK)
PUT – updates (or creates) a resource on the basis of the request information; the desired Status Code for this operation is 200 (OK) for a successful update along with the content of the response body, 204 (NO CONTENT) if no content is returned in the body but the resource has been updated, or 201 (CREATED) upon successful creation
POST – creates resources, in particular subordinate ones; the desired Status Code for this operation is 201 (CREATED)
DELETE – deletes resources identified by a URI; the desired Status Code for this operation is 200 (OK) along with a response body, or 204 (NO CONTENT) if no content is returned but the resource has been deleted
URL Must contain:
the context root path
the endpoint path (which defines a specific Converge EMS interface)
the resource path (which contains either the resource
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 15 of 69
Table 2: Requirements for HTTP Requests
for the CRUD type interface, or a method name for other interface types)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 16 of 69
HTTP Responses
Converge EMS sends Responses to each Request sent over the API. The Response must comply with the following requirements:
Element Requirement
HTTP Message Type Response (mandatory)
HTTP Message must contain a header (the content of which depends on the endpoint and the method in the corresponding Request)
may contain a message body (only for some endpoints and methods in the corresponding Request)
HTTP Version HTTP/1.1
Status Codes OK (200) – the request has succeeded; the information returned in the response depends on the method used in the request
CREATED (201) – the request has been fulfilled and a new resource has been created
NO CONTENT (204) – the request has been fulfilled but does not need to return the message body (this response may include new or updated information in the header)
UNAUTHORIZED (401) – the request requires user authentication
FORBIDDEN (403) – the request has been recognised, but the server has refused to fulfil it
INVALID DATA (456) – the request has been rejected due to incorrect data that could not be validated
INTERNAL SERVER ERROR (500) – the request could not be fulfilled due to an unexpected server error
Table 3: Requirements for HTTP Responses
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 17 of 69
Common RESTful Endpoints
The common REST Web Services endpoint is <contextRoot>/rest, where ‘contextRoot’ can be either convergeEMS, or any other, as modified for a specific vendor solution.
The following table lists all endpoints that are currently supported by Converge EMS:
Endpoint Endpoint URL Endpoint Description
Authentication Endpoint <contextRoot>/rest/ security
Security endpoint for login and logout.
Domain Objects
Endpoint
<contextRoot>/rest/ domainObjects
Endpoint for Domain Object API. Used for managing CRUD access to the Domain Objects.
Also used for read access to the Meta Model, when access to individual Meta Model Classes, Fields and Validators as Domain Objects is required.
Meta Model Endpoint <contextRoot>/rest/ metaModels
Endpoint for Meta Model API. Used for managing access to the Meta Model.
Business Component
Endpoint
<contextRoot>/rest/ businessLogic
Endpoint for Business Component API.
Used for invocation of Business Components methods.
Also used for initializing Meta Model re-discovery.
Document Retrieval
Endpoint
<contextRoot>/rest/ documentRetrieval
Endpoint for Document Retrieval API.
Used for retrieving documents.
Table 4: Common RESTful Endpoints
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 18 of 69
Converge EMS REST Web Services API – Authorization Requests
Login
Description Logs in a new user
HTTP Method PUT
URL http://a.b.c.d:port/<contextRoot>/rest/security/login
Header Not required
Message Body The following information in the xml format must be included in the message body:
<login><username>name</username><password>value</password></login>
Table 5: Login Request
Note: Login can be replaced with a Web Login to provide for a web browser login via a web form. See Web Login.
Login Request Example
Login Response If the login is successful, the token is returned in the message body with the Status OK (200). The returned token must be used in all subsequent messages in the ‘Authorization’ header.
PUT http://localhost:8080/convergeEMS/rest/security/login HTTP/1.1
Accept‐Encoding: gzip,deflate
Accept: text/plain
Content‐Type: application/xml
Content‐Length: 73
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) <login><username>admin</username><password>adminpassword</password></login>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 19 of 69
If the login fails, for example due to incorrect credentials, the UNAUTHORIZED (401) Status is returned.
Login Response Example (OK)
Login Response Example (Unauthorized)
HTTP/1.1 401 Unauthorized
Server: Apache‐Coyote/1.1
ErrorMessage: User Un‐Authorized
WWW‐Authenticate: TOKEN
Content‐Type: text/plain
Transfer‐Encoding: chunked
Date: Thursday, 16 April 2015 16:53:16 GMT User Un‐Authorized
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Set‐Cookie: JSESSIONID=D38E9D0E460311BFEB5AD3FEDBD68796; Path=/convergeEMS/;
HttpOnly
Content‐Type: text/plain
Transfer‐Encoding: chunked
Date: Thursday, 16 April 2015 16:53:16 GMT admin‐‐ D38E9D0E460311BFEB5AD3FEDBD68796
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 20 of 69
Logout
Description Logs out a user
HTTP Method DELETE
URL http://a.b.c.d:port/<contextRoot>/rest/security/login
*Note: The correct URL is /rest/security/login as the operation of logging out is a delete of the ‘login’ resource.
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin- - 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body Empty
Table 6: Logout Request
Note: Logout can be replaced with a Web Logout to provide for a web browser login via a web form. See Web Logout.
Logout Request Example
Logout Response If the logout is successful, the OK Status (200) is returned.
If the login fails, an ERROR Status is returned.
Logout Response Example (OK)
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Thursday, 16 April 2015 16:53:16 GMT
DELETE http://localhost:8080/convergeEMS/rest/security/login HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 21 of 69
Logout Response Example (Error)
HTTP/1.1 404 Not Found
Server: Apache‐Coyote/1.1
Content‐Type: text.html;charset=utf‐8
Content‐Length: 967
Date: Thursday, 16 April 2015 16:53:16 GMT <html><head> <title>Apache Tomcat/7.0.37 – Error report</title><style>...
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 22 of 69
Web Login
Description Logs in a user via a web form (when logging in in a browser)
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/security/web-login
Header Not required
Message Body Two form parameters, username and password
Table 7: Web Login Request
Web Login Request Example
Web Login Response If the login is successful, the user is redirected to <contextRoot>/main/main.html through the location header. The response also includes the security token in the ‘Authorization’ header and in the Cookie.
If the login fails, the user is redirected to the login page, and an error message is returned.
POST http://localhost:8080/convergeEMS/rest/security/web‐login HTTP/1.1
Host: 127.0.0.1:6090
User‐Agent: Mozilla/5.0 (X11; U; Linux i686; en‐US; rv:1.9.2.13) Gecko/20101206
Ubuntu/10.04 (lucid) Firefox/3.6.13
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept‐
Language: en‐gb, chrome://global/locale/intl.properties;q=0.5 Accept‐Encoding:
gzip,deflate
Accept‐Charset: ISO‐8859‐1,utf‐8;q=0.7,*;q=0.7
Keep‐Alive: 115
Connection: keep‐alive
Referer: http://127.0.0.1:6090/convergeEMS/login.jsp
Content‐Type: application/x‐www‐form‐urlencoded
Content‐Length: 39 username=admin&x=32&y=29&password=admin
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 23 of 69
Web Login Response Example (with Redirect)
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
X‐Powered‐By: Servlet 2.5; JBoss‐5.0/JBossWeb‐2.1
Accept‐Ranges: bytes
ETag: W/"919‐1297776468000"
Last‐Modified: Thursday, 16 April 2015 16:53:16 GMT
Content‐Type: text/html
Content‐Length: 919
Date: Thursday, 16 April 2015 16:53:16 GMT <!DOCTYPE HTML PUBLIC "‐//W3C//DTD HTML> ....
GET /convergeEMS/main/main.html HTTP/1.1
Host: 127.0.0.1:6090
User‐Agent: Mozilla/5.0 (X11; U; Linux i686; en‐US; rv:1.9.2.13) Gecko/20101206
Ubuntu/10.04 (lucid) Firefox/3.6.13
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept‐
Language: en‐gb, chrome://global/locale/intl.properties;q=0.5 Accept‐Encoding:
gzip,deflate
Accept‐Charset: ISO‐8859‐1,utf‐8;q=0.7,*;q=0.7
Keep‐Alive: 115 Connection: keep‐alive
Referer: http://127.0.0.1:6090/convergeEMS/login.jsp
Cookie: JSESSIONID=819B5BA280CB23BD57491136DB192B7D;
SECURITY_TOKEN=admin‐‐ 97e00033‐0cfe‐4b3f‐b3f1‐cfa6e7648f23
If‐Modified‐Since: Thursday, 16 April 2015 16:53:16 GMT
If‐None‐Match: W/"919‐1297771918000"
HTTP/1.1 302 Moved Temporarily
Server: Apache‐Coyote/1.1
X‐Powered‐By: Servlet 2.5; JBoss‐5.0/JBossWeb‐2.1
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Set‐Cookie: SECURITY_TOKEN=admin‐‐97e00033‐0cfe‐4b3f‐b3f1‐cfa6e7648f23; Path=/
Location: http://127.0.0.1:6090/convergeEMS/main/main.html Content‐Length: 0
Date: Thursday, 16 April 2015 16:53:16 GMT
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 24 of 69
Web Logout
Description Logs out a user through a web browser
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/security/web-logout
Header Obligatory: The token in the Cookie
Message Body Empty
Table 8: Web Logout Request
Web Logout Request Example
Web Logout Response If the login is successful, the user is redirected to the login page <contextRoot>/login.jsp.
If the login fails, the user is redirected to the login page, and an error message is returned.
Web Logout Response Example
HTTP/1.1 302 Moved Temporarily
Server: Apache‐Coyote/1.1
X‐Powered‐By: Servlet 2.5; JBoss‐5.0/JBossWeb‐2.1
Location: http://127.0.0.1:6090/convergeEMS/login.jsp
POST http://localhost:8080/convergeEMS/rest/security/web‐logout HTTP/1.1
Host: 127.0.0.1:6090
User‐Agent: Mozilla/5.0 (X11; U; Linux i686; en‐US; rv:1.9.2.13) Gecko/20101206
Ubuntu/10.04 (lucid) Firefox/3.6.13
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept‐
Language: en‐gb, chrome://global/locale/intl.properties;q=0.5 Accept‐Encoding:
gzip,deflate
Accept‐Charset: ISO‐8859‐1,utf‐8;q=0.7,*;q=0.7
Keep‐Alive: 115
Connection: keep‐alive
Referer:
http://127.0.0.1:6090/convergeEMS/main/D93D980CFB734DEDD87EB1BF83D4EBAF.cache.html
Cookie: JSESSIONID=819B5BA280CB23BD57491136DB192B7D; SECURITY_TOKEN= admin‐‐97e00033‐
0cfe‐4b3f‐b3f1‐cfa6e7648f23
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 25 of 69
Content‐Length: 0
Date: Thursday, 16 April 2015 16:53:16 GMT
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 26 of 69
Web Verify
Description Verifies if a token is still active
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/security/web-verify
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin- - 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body Empty
Table 9: Web Verify Request
Web Verify Response If the token is still active, the Status Code is OK (200).
If the token is not active any more, and Error Status is returned.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 27 of 69
Converge EMS REST Web Services API – Domain Object Requests
Create Domain Object
Description Creates a new Domain Object instance
HTTP Method PUT
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName}
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body The following is the XML format that must be used in the message body to describe the Domain Object instance to be created (see also the example below):
<metaModelClassName classVersion=”x.y”>
<name>name1</name>
<field1>value1</field1>
<field2>value2</field2>
</metaModelClassName>
Table 10: Create Domain Object Request
Create Domain Object Request Example
PUT http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber HTTP/1.1
Accept‐Encoding: gzip,deflate
Accept: text/html
Content‐Type: text/plain; charset=UTF‐8
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Content‐Length: 349
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) <Subscriber classVersion="1.0">
<name>subscriber1</name>
<owner>ConvergeMSS<owner>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 28 of 69
Create Domain Object Response If the request is successful, the response is sent with an empty message body, and the CREATED (201) Status Code.
If the request fails, the possible status can be FORBIDDEN (403) if the user does not have the create access to the Meta Model Class with the name ‘metaModelClassName’, or INVALID DATA (456) if validation fails on the object and its fields.
Create Domain Object Response Example
HTTP/1.1 201 Created
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Thursday, 16 April 2015 16:53:16 GMT
<userLabel>Subscriber‐1</userLabel>
<description>This is Subscriber‐1</description>
<phone>+353‐166380000</phone>
<address>Century Court, Dun Laoghaire</address>
</Subscriber>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 29 of 69
Read Domain Object
Description Reads all Domain Object instances meeting the specified criteria
HTTP Method GET
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName}
http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName} /{version}*
*Note: An optional {version} path should be used to specify a particular version of the Meta Model Class. If it is omitted, the latest version is used.
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Optional: ‘filter’ header – this is an optional header used if not all instances of some Domain Object are required, but only particular instances as defined in the filtering conditions. See Read Domain Object Request Example (with Filter and Parameters).
A filter example:
<filter operator="and"><condition field="name" operator="eq"
value="subscriber1"/></filter>
Note: See APPENDIX – Filter Operators to learn what syntax and operators can be used for filters here.
Message Body Not required
Query Parameters
Two parameters can be used, start and limit.
start: the index of the first object to be returned
limit: the maximum number of instances to be returned
See Read Domain Object Request Example (with Filter and Parameters).
Note: start should be set to 0 and limit to -1 to return all instances. If neither of these parameters is used, all instances are returned as well.
Table 11: Read Domain Object Request
Read Domain Object Request Example (without Filter or Parameters)
GET http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber HTTP/1.1
Accept‐Encoding: gzip,deflate
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 30 of 69
The above request returns all Subscribers.
Read Domain Object Request Example (with Filter and Parameters)
The above request returns only the first ten Subscribers that meet the filter conditions. The number and index of the desired Subscribers are defined in the endpoint parameters.
Note: See APPENDIX – Filter Operators to learn what operators and syntax can be used for filters here.
Read Domain Object Response A response is sent with a list of Domain Objects in the following format:
<list>
<MetaModelClassName classVersion="1.0" expanded=”no”>
<name>object1</name>
<field1 >value1</field1>
<field2 >value2</field2>
</MetaModelClassName> < MetaModelClassName version="1.0">
<name>object2</name>
<field1 >value1</field1>
GET http://localhost:8080/convergeEMS/rest/domainObjects/
Subscriber?start=0&limit=10 HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
filter: <filter operator="and"><condition field="name" operator="contains"
value="subscriber"/></filter>
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 31 of 69
If the request is successful, the status of the response is OK (200).
If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’.
Read Domain Object Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
startRow: 0
endRow: 2
totalRows: 2
Cache‐Control: max‐age=0
Content‐Type: text/xml
Date: Thursday, 16 April 2015 16:53:16 GMT <list>
<Subscriber classVersion="1.0" expanded=”no”>
<name>subscriber1</name>
<discoveredName>N/A</discoveredName>
<discoveredHiddenId>‐1</discoveredHiddenId>
<namingOs>convergeEMS </namingOs>
<owner>convergeEMS</owner>
<createdBy>admin</createdBy>
<createDate>16/04/2015 16:53:16</createDate>
<modifiedBy>N/A</modifiedBy>
<modifyDate>N/A</modifyDate>
<planned>true</planned>
</Subscriber> <Subscriber classVersion="1.0" expanded=”no”>
<name>subscriber2</name>
<discoveredName>N/A</discoveredName>
<discoveredHiddenId>‐1</discoveredHiddenId>
<namingOs>convergeEMS</namingOs>
<owner>OS‐SM‐Amartus</owner>
<field2 >value2</field2>
</MetaModelClassName>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 32 of 69
Three extra header parameters are sent in the response: startRow, endRow and totalRows. These are useful for paging in the GUI or for iterators:
startRow: specifies the index of the first row returned endRow: specifies the index of the last row returned
totalRows: specifies the total number of rows that meet the request
<createdBy>admin</createdBy>
<createDate>16/04/2015 16:53:16</createDate>
<modifiedBy>N/A</modifiedBy>
<modifyDate>N/A</modifyDate>
<planned>true</planned>
</Subscriber>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 33 of 69
Update Domain Object
Description Updates a Domain Object instance
HTTP Method POST
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName}
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body
The following is the XML format that must be used in the message body to describe the Domain Object instance to be updated (see also the example below):
<metaModelClassName classVersion=”x.y”>
<name>name1</name>
<field1>value1</field1>
<field2>value2</field2>
</metaModelClassName>
Table 12: Update Domain Object Request
Update Domain Object Request Example
POST http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber HTTP/1.1
Accept‐Encoding: gzip,deflate
Accept: text/html
Content‐Type: text/xml
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Content‐Length: 271
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) <Subscriber classVersion="1.0">
<name>subscriber1</name>
<description>New Description</description>
</Subscriber>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 34 of 69
Update Domain Object Response If the request is successful, the status of the response is OK (200), and the Message Body is empty.
If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’, or INVALID DATA (456) if validation fails on the object and its fields.
Update Domain Object Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Thursday, 16 April 2015 16:53:16 GMT
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 35 of 69
Delete Domain Object
Description Deletes a Domain Object instance
HTTP Method DELETE
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/{metaModelClassName} /{objectName}
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body
Not required
Table 13: Delete Domain Object Request
Delete Domain Object Request Example
Delete Domain Object Response If the request is successful, the response is sent with an empty message body, and the NO CONTENT (204) Status Code.
If the request fails, the possible status is FORBIDDEN (403) if the user does not have the delete access to the Meta Model Class with the name ‘metaModelClassName’.
Delete Domain Object Response Example
HTTP/1.1 204 No Content
Server: Apache‐Coyote/1.1
Date: Thursday, 16 April 2015 16:53:16 GMT
DELETE
http://localhost:8080/convergeEMS/rest/domainObjects/Subscriber/subscriber2
HTTP/1.1
Accept‐Encoding: gzip,deflate
Accept: text/html
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 36 of 69
Converge EMS REST Web Services API – Meta Model Requests
Read Meta Model Class, Fields and Validators
Description Reads a Meta Model Class with its fields and validators
HTTP Method GET
URL http://a.b.c.d:port/<contextRoot>/rest/metaModels/{metaModelClassName}
http://a.b.c.d:port/<contextRoot>/rest/metaModels/{metaModelClassName} /{version}
*Note: An optional {version} path should be used to specify a particular version of the Meta Model Class. If it is omitted, the latest version is used.
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body
Not required
Table 14: Read Meta Model Class, Fields and Validators Request
Read Meta Model Class, Fields and Validators Request Example
Read Meta Model Class, Fields and Validators Response If the request is successful, the status of the response is OK (200), and the response contains all Meta Data from the corresponding ‘metaModelClassName.meta.xml’ file, for the class, its fields and all validators. The content depends on the Meta Model Class.
GET http://localhost:8080/convergeEMS/rest/metaModels/Subscriber HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 37 of 69
Read Meta Model Class, Fields and Validators Response Example Only an excerpt of a response is provided here as an example. The original response was much longer, but this example is to show the format in which elements of the response are presented.
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Type: text/xml
Transfer‐Encoding: chunked
Date: Thursday, 16 April 2015 16:53:16 GMT
<MetaModelClass name=”Subscriber”
compressedName=”Subscriber_1.0”
className=”Subscriber”
title=”Subscriber”
namespace=”service/Subscriber/v1.0”
module=”entities”
expanded=”true”
isAbstract=”false”
inheritsFrom=”CommonObjectInfo”
inheritsFromVersion=”1.0”
containedIn=”root”
userAccess=”crud”
version=”1.0”
hasObject=”true”
discover=”yes”
aggregated=”no”
description=””
deprecated=”false”>
<fields>
<field name=”CommonObjectInfo_1.0_name” metaClassName=”CommonObjectInfo”
compressedName=”a_name” fieldname=”name” title=”Name” type=”text”
primaryKey=”true” foreignKey=”” rootValue=”” required=”true” length=”100”
Multiple=”false” detail=”false” hidden=”false” canEdit=”createOnly”
description=”name” globallySet=”false” canBeOverridden=”false” contained=”never”
metaClassId=”CommonObjectInfo_1.0” metaClassVersion=”” ordinalPosition=”0”
defaultValue=”” monitored=”false” pattern=”” inherited=”true”>
<validators>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 38 of 69
<validator name="CommonObjectInfo_1.0_name_lengthRange" metaFieldName="name"
metaFieldId="CommonObjectInfo_1.0_name" clientOnly="false" errorMessage="Length
must be 3‐100 characters" isServerSide="true" maxValue="100" minValue="3"
stopIfFalse="false" type="lengthRange" />
<validator name="CommonObjectInfo_1.0_name_isString" metaFieldName="name"
metaFieldId="CommonObjectInfo_1.0_name" clientOnly="false" errorMessage="Value
must be a string" isServerSide="true" stopIfFalse="false" type="isString" />
</validators>
</field> <field name=...>
</field>
</fields>
</MetaModelClass>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 39 of 69
Read All Meta Model Classes with Fields and Validators
Description Reads all Meta Model Classes with their fields and validators
HTTP Method GET
URL http://a.b.c.d:port/<contextRoot>/rest/metaModels
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body
Not required
Table 15: Read All Meta Model Classes, Fields and Validators Request
Read All Meta Model Classes with Fields and Validators Request Example
Read All Meta Model Classes with Fields and Validators Response If the request is successful, the status of the response is OK (200), and the response contains all Meta Data from all ‘*.meta.xml’ files, for the classes, all their fields and all validators. The content depends on the Meta Model Classes.
Read All Meta Model Classes with Fields and Validators Response Example The response format is the same as in Read Meta Model Class, Fields and Validators Response Example, but it lists all, not just on Meta Model Class.
GET http://localhost:8080/convergeEMS/rest/metaModels HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 40 of 69
Get Meta Model Hierarchy
Description Returns the inheritance hierarchy for a specific class
HTTP Method GET
URL http://a.b.c.d:port/<contextRoot>/rest/metaModels/hierarchy /{metaModelClassName}
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body
Not required
Table 16: Get Meta Model Hierarchy Request
Get Meta Model Hierarchy Request Example
Get Meta Model Hierarchy Response If the request is successful, the status of the response is OK (200), and the response contains a list of base class names.
Get Meta Model Hierarchy Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Type: text/xml
Transfer‐Encoding: chunked
Date: Thursday, 16 April 2015 16:53:16 GMT <list>
<string>CommonObjectInfo</string>
GET http://localhost:8080/convergeEMS/rest/metaModels/hierarchy/Subscriber
HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐Http‐Client/4.1.1 (java 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 41 of 69
<string>Subscriber</string>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 42 of 69
Read Meta Model Classes (Domain Object API for Meta Model Access)
Domain Object API can be used for accessing Meta Model if it is required to have the read access to Meta data of Meta Model Classes, fields and validators individually. Below is an example for reading Meta Model Classes only.
This Domain Object API can be used for reading all Meta Model Classes, several Meta Model Classes that meet the specified criteria, or a single Meta Model Class.
Description Reads Meta Model Class instances that meet the specified criteria
HTTP Method
GET
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelClass
http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelClass/{version}
*Note: An optional {version} path should be used to specify a particular version of the Meta Model Class. If it is omitted, the latest version is used.
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Optional: ‘filter’ header – this is an optional header. If it is not used, all Meta Model Classes are returned. If used, then only Meta Model Classes that meet the conditions defined in the filter are returned. See Read Meta Model Classes Request Example (with Filter and Parameters).
A filter example:
<filter operator="and"><condition field="name" operator="eq" value="subscriber1"/></filter>
Note: See APPENDIX – Filter Operators to learn what operators and syntax can be used for filters here.
Message Body
Not required
Query Parameters
Two parameters can be used, start and limit.
start: the index of the first object to be returned
limit: the maximum number of instances to be returned
See Read Meta Model Classes Request Example (with Filter and Parameters).
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 43 of 69
Table 17: Read Meta Model Classes (Domain Object API) Request
Read Meta Model Classes Request Example (without Filter or Parameters)
The above request returns all Meta Model Classes.
Read Meta Model Classes Request Example (with Filter and Parameters)
The above request returns only the first ten Meta Model Classes that meet the filter conditions. The number and index of the Meta Model Classes are defined in the endpoint parameters.
Note: See APPENDIX – Filter Operators to learn what operators and syntax can be used for filters here.
Read Meta Model Classes Response A response is sent with a list of Domain Objects in the following format:
GET http://localhost:8080/convergeEMS/rest/domainObjects/MetaModelClass
?start=0&limit=10 HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
filter: <filter operator="and"><condition field="name" operator="eq"
value="Subscriber_1.0"/></filter>
GET http://localhost:8080/convergeEMS/rest/domainObjects/MetaModelClass HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
Note: start should be set to 0 and limit to -1 to return all instances. If neither of these parameters is used, all instances are returned as well.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 44 of 69
If the request is successful, the status of the response is OK (200).
If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’.
Read Meta Model Classes Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
startRow: 0
endRow: 2
totalRows: 2
Content‐Type: text/xml
Transfer‐Encoding: chunked
Date: Thursday, 16 April 2015 16:53:16 GMT <list>
<MetaModelClass classVersion=”1.0” expanded=”no”>
<name>Subscriber_1.0</name>
<compressedName>Subscriber_1.0</compressedName> <className>Subscriber</className>
<title>Subscriber</title>
<namespace>service/Subscriber/v1.0</namespace>
<module>entities</module>
<expanded>true</expanded>
<isAbstract>false</isAbstract> <inheritsFrom>CommonObjectInfo</inheritsFrom>
<list>
<MetaModelClass version="1.0" expanded=”no”>
<name>class1</name>
<field1 >value1</field1 >
<field2 >value2</field2 >
</MetaModelClass> < MetaModelClass version="1.0" expanded=”no”>
<name>class2</name>
<field1 >value1</field1 >
<field2 >value2</field2 >
</MetaModelClass>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 45 of 69
Three extra header parameters are sent in the response: startRow, endRow and totalRows. These are useful for paging in the GUI or for iterators:
startRow: specifies the index of the first row returned
endRow: specifies the index of the last row returned totalRows: specifies the total number of rows that meet the request
<inheritsFromVersion>1.0</inheritsFromVersion> <containedIn>root</containedIn>
<userAccess>crud</userAccess>
<version>1.0</version>
<hasObject>true</hasObject>
<discover>yes</discover>
<aggregated>no</aggregated>
<description></description>
<deprecated>false</deprecated>
</MetaModelClass>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 46 of 69
Read Meta Model Fields (Domain Object API for Meta Model Access)
Domain Object API can be used for accessing Meta Model if it is required to have the read access to Meta data of Meta Model Classes, fields and validators individually. Below is an example for reading Meta Model fields only.
This Domain Object API can be used for reading all Meta Model fields, several Meta Model fields that meet the specified criteria, or a single Meta Model field.
Description Reads Meta Model field instances that meet the specified criteria
HTTP Method
GET
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelField
http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelField/{version}
*Note: An optional {version} path should be used to specify a particular version of the Meta Model Field. If it is omitted, the latest version is used.
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Optional: ‘filter’ header – this is an optional header. If it is not used, all Meta Model Fields are returned. If used, then only Meta Model Fields that meet the conditions defined in the filter are returned. See the request example below.
A filter example:
<filter operator="and"><condition field="required" operator="eq" value="true"/></filter>
Note: See APPENDIX – Filter Operators to learn what syntax and operators can be used for filters here.
Message Body
Not required
Query Parameters
Two parameters can be used, start and limit.
start: the index of the first object to be returned
limit: the maximum number of instances to be returned
See the request example below.
Note: start should be set to 0 and limit to -1 to return all instances. If neither of
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 47 of 69
Table 18: Read Meta Model Fields (Domain Object API) Request
Read Meta Model Fields Request Example
The above request returns only the first ten Meta Model Fields that meet the filter conditions. The number and index of the desired Meta Model Classes are defined in the endpoint parameters.
Note: See APPENDIX – Filter Operators to learn what operators and syntax can be used for filters here.
Read Meta Model Fields Response A response is sent with a list of Domain Objects in the following format:
<list>
<MetaModelField classVersion="1.0" expanded=”no”>
<name>field1</name>
<field1 >value1</field1 >
<field2 >value2</field2 >
</MetaModelField> <MetaModelField classVersion="1.0" expanded=”no”>
<name>field1</name>
<field1 >value1</field1 >
<field2 >value2</field2 >
</MetaModelField>
</list>
GET http://localhost:8080/convergeEMS/rest/domainObjects
MetaModelField?start=0&limit=10 HTTP/1.1
Accept‐Encoding: gzip,deflate
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5)
filter: <filter operator="and"><condition field="required" operator="eq"
value="true"/></filter>
these parameters is used, all instances are returned as well.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 48 of 69
If the request is successful, the status of the response is OK (200).
If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’.
Read Meta Model Fields Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
startRow: 0
endRow: 2
totalRows: 2
Content‐Type: text/xml
Transfer‐Encoding: chunked
Date: Thursday, 16 April 2015 16:53:16 GMT <list>
<MetaModelField classVersion=”1.0” expanded=”no”>
<name>AccessSpecification_1.0_associateRemoteObjects</name>
<compressedName>a_description</compressedName> <fieldName>description</fieldName>
<title>Description</title>
<type>text</type>
<primaryKey>false</primaryKey>
<foreignKey></foreignKey>
<rootValue></rootValue>
<required>true</required>
<length>120</length>
<multiple>false</multiple>
<detail>true</detail>
<hidden>false</hidden>
<canEdit>createAndUpdate</canEdit>
<description>description</description>
<globallySet>false</globallySet>
<canBeOverridden>false</canBeOverridden>
<contained>never</contained> <metaClassName>CommonObjectInfo</metaClassName>
<metaClassId>CommonObjectInfo_1.0</metaClassId>
<metaClassVersion></metaClassVersion>
<ordinalPosition>6</ordinalPosition>
<defaultValue></defaultValue>
<monitored>false</monitored>
<pattern></pattern>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 49 of 69
Three extra header parameters are sent in the response: startRow, endRow and totalRows. These are useful for paging in the GUI or for iterators:
startRow: specifies the index of the first row returned endRow: specifies the index of the last row returned
totalRows: specifies the total number of rows that meet the request
<inherited>true</inherited>
</MetaModelField>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 50 of 69
Read Meta Model Field Validators (Domain Object API for Meta Model Access)
Domain Object API can be used for accessing Meta Model if it is required to have the read access to Meta data of Meta Model Classes, fields and validators individually. Below is an example for reading Meta Model validators only.
This Domain Object API can be used for reading all Meta Model validators, several Meta Model validators that meet the specified criteria, or a single Meta Model validator.
Description Reads Meta Model validator instances that meet the specified criteria
HTTP Method
GET
URL http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelFieldValidator
http://a.b.c.d:port/<contextRoot>/rest/domainObjects/MetaModelFieldValidator /{version}
*Note: An optional {version} path should be used to specify a particular version of the Meta Model Field Validator. If it is omitted, the latest version is used.
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Optional: ‘filter’ header – this is an optional header. If it is not used, all Meta Model Field Validators are returned. If used, then only Meta Model Field Validators that meet the conditions defined in the filter are returned. See the request example below.
A filter example:
<filter operator="and"><condition field="type" operator="eq"
value="integerRange"/></filter>
Note: See APPENDIX – Filter Operators to learn what syntax and operators can be used for filters here.
Message Body
Not required
Query Parameters
Two parameters can be used, start and limit.
start: the index of the first object to be returned
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 51 of 69
Table 19: Read Meta Model Field Validators (Domain Object API) Request
Read Meta Model Field Validators Request Example
Read Meta Model Field Validators Response A response is sent with a list of Domain Objects in the following format:
<list>
<MetaModelFieldValidator classVersion="1.0" expanded=”no”>
<name>validator1</name>
<field1 >value1</field1 >
<field2 >value2</field2 >
</MetaModelFieldValidator>
< MetaModelFieldValidator classVersion="1.0" expanded=”no”>
<name>validator2</name>
<field1 >value1</field1 >
<field2 >value2</field2 >
</MetaModelFieldValidator>
</list>
GET http://localhost:8080/convergeEMS/rest/domainObjects/
MetaModelFieldValidator?start=0&limit=10 HTTP/1.1
Accept‐Encoding: gzip,deflate
Accept: text/html
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Connection: Keep‐Alive
Host: localhost:8080
User‐Agent: Apache‐HttpClient/4.1.1 (java 1.5) filter: <filter operator="and"><condition field="type" operator="eq"
value="integerRange"/></filter>
limit: the maximum number of instances to be returned
See the request example below.
Note: start should be set to 0 and limit to -1 to return all instances. If neither of these parameters is used, all instances are returned as well.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 52 of 69
Three extra header parameters are sent in the response: startRow, endRow and totalRows. These are useful for paging in the GUI or for iterators:
startRow: specifies the index of the first row returned endRow: specifies the index of the last row returned
totalRows: specifies the total number of rows that meet the request
If the request is successful, the status of the response is OK (200).
If the request fails, the response status is FORBIDDEN (403) if the user does not have the read access to the Meta Model Class with the name ‘metaModelClassName’.
Read Meta Model Field Validators Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
X‐Powered‐By: Servlet 2.5; JBoss‐5.0/JBossWeb‐2.1
startRow: 0
endRow: 1
totalRows: 1
Content‐Type: text/xml
Date: Thursday, 16 April 2015 16:53:16 GMT
Content‐Length: 413 <list>
<MetaModelFieldValidator version="1.0">
<name>CommonObjectInfo_1.0_name_isString</name>
<validatorType>isString</validatorType>
<metaFieldName>name</metaFieldName>
<metaFieldId>CommonObjectInfo_1.0_name</metaFieldId>
<stopIfFalse>false</stopIfFalse>
<isClientOnly>false</isClientOnly>
<errorMessage>Value must be a string</errorMessage>
<isServerSide>true</isServerSide>
</MetaModelFieldValidator>
</list>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 53 of 69
Re-discover Meta Model (Business Component API for Meta Model Discovery)
As mentioned in Meta Model Object REST Web Services Interface, Business Component API may be used for re-discovery of the Meta Model. In such a case, the following request may be sent via this API.
Description Re-discover the Meta Model by discovering new classes and new class versions
HTTP Method
POST
URL http://a.b.c.d:port/<contextRoot>/rest/businessLogic /metaModelDiscoveryService/discover
Header Obligatory: ‘Authorization’ header containing the token (e.g. TOKEN admin-- 3510EBCC2B5555AEBA3FEA6F6EFF3DE5)
Message Body
Not required
Table 20: Re-discover Meta Model (Business Component API) Request
Re-discover Meta Model Request Example
Re-discover Meta Model Response If the request is successful, the status of the response is OK (200), and an empty message body.
POST http://localhost:8080/convergeEMS/rest/businessLogic/
spring:metaModelDiscoveryService/discover HTTP/1.1
Accept‐Encoding: gzip,deflate
Content‐Type: application/xml
Authorization: TOKEN admin‐‐ 3510EBCC2B5555AEBA3FEA6F6EFF3DE5
Content‐Length: 0
Host: localhost:8080
Connection: Keep‐Alive
User‐Agent: Apache‐HttpClient/4.1.1 (jave 1.5)
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 54 of 69
Re-discover Meta Model Response Example
HTTP/1.1 200 OK
Server: Apache‐Coyote/1.1
Content‐Length: 0
Date: Thursday, 16 April 2015 16:53:16 GMT
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 55 of 69
Converge EMS REST Web Services Integration
REST Web Services Integration Interface is used to invoke the API of external applications to integrate with ANY software application using the REST interface. Another capability of this interface is to integrate with another Converge EMS instance.
Figure 5: REST Web Services Integration Interface
Converge EMS can use the REST Web Services API for integration with:
EMSs / NMSs that provide the REST Web Services API.
Any Software Application that provides the REST Web Services API, including any OSS.
Network Devices that provide the REST Web Services API.
Other Converge EMS instances.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 56 of 69
Converge EMS REST Web Services Integration – Message Exchange
The following sequence diagram shows the message exchange between the Converge EMS and external applications.
Figure 6: Converge EMS REST Web Services Integration Message Exchange Matrix
The message exchange matrix consists of the following REQUEST / RESPONSE messages, where Login and Logout must be first and last, respectively.
After Converge EMS logs in, it can create, read, update and delete Domain Objects through the Domain Object API; see Converge™ EMS REST W eb Services AP I – Domain Object Requests.
The security can be disabled if not required. If disabled, there will be no login and logout messages, and all other messages will not require authorization / token.
The interface can be used with or without Mediation. For Mediation details please refer to appropriate Mediation customization documents.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 57 of 69
Tip: If the external EMS/NMS/Network application uses the same Meta Model and the same REST Web Services Interface as Converge EMS, there is NO NEED for Mediation.
Mediation is also NOT REQUIRED at integration with another instance of Converge EMS.
Request Name Request Description Request Elements Response Elements
Login Logging in to interface http(s) request, PUT, URI, credentials
http(s) response, status token
Domain Object
Interface
Creation, Reading, Updating, and Deleting Domain Objects (CRUD) through Domain Object API
http(s) request, GET / PUT / POST / DELETE, URI, authorization
()
Logout Logging out of interface http(s) request, DELETE, URI, token
http(s) response, status
Table 21: Converge EMS REST Web Services Integration Message Exchange Matrix
The default HTTP Requests and Responses are described in HTTP Requests and HTTP Responses, respectively. Mediation can be used to modify the default messages.
The default Restful Endpoints are described in Common RESTful Endpoints. For REST Web Services Integration, the Authentication and the Domain Objects Endpoints are used. Mediation can be used to modify the default endpoints.
The default Authentication (login and logout messages) are described in Converge EMS™ REST Web Services API – Authorization Requests. Mediation can be used to modify the default messages. Authentication can be also disabled by configuring Operations System without logging credentials.
The default messages for CRUD operations are the same as the ones used in Domain Object API – see Converge EM S™ REST Web Services AP I – Domain Object Requests. Mediation can be used to modify the default messages.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 58 of 69
Alarms and Stats
The Stats are under model_home/common/measurements model_home/resource/measurements and model_home/service/measurements. The Alarm objects are under ModelHome/common/event and model_home/service/event.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 59 of 69
Index
A
Authentication Endpoint, 21
B
Business Component Endpoint, 21
C
Converge EMS REST Web Services API Authorization Requests, 22 Business Component API, 17
Document Retrieval API, 17
Domain Object API, 17, 61 Domain Object Requests, 31 Login, 16, 61
Logout, 17, 61 Message Exchange, 16, 60 Meta Model API, 17 Meta Model Requests, 40
Converge EMS REST Web Services Integration, 59
Converge EMS RESTful API Introduction, 10
Common RESTful Endpoints, 21
Create Domain Object, 31 Request Example, 31 Response, 32 Response Example, 32
CREATED, 20
D
DELETE, 18
Delete Domain Object, 39 Request Example, 39 Response, 39 Response Example, 39
Document Retrieval Endpoint, 21
Domain Object REST Web Services Interface, 13
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 60 of 69
Domain Objects Endpoint, 21
F
Filter Operators, 67 allEq, 69
begins, 69
between, 69 contains, 69
ends, 69
eqField, 69
ge, 69
geField, 69 gt, 69
gtField, 69
iEquals, 70
in, 70
iNotEquals, 70
inSet, 70 isEmpty, 70
isNotEmpty, 70
isNotNull, 70 isNull, 70
le, 70
leField, 70
lt, 70
ltField, 70
ne, 70
neField, 70
notInSet, 71
FORBIDDEN, 20
G
GET, 18
Get Meta Model Hierarchy, 44 Request Example, 44 Response, 44 Response Example, 44
Glossary, 9
H
HTTP Requests, 18 DELETE, 18 GET, 18 HTTP Message, 18
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 61 of 69
HTTP Message Type, 18
HTTP Methods, 18
HTTP Version, 18 POST, 18 PUT, 18 URL, 18
HTTP Responses, 20 HTTP Message, 20
HTTP Message Type, 20
Status Codes, 20
I
INTERNAL SERVER ERROR, 20
INVALID DATA, 20
L
Login, 22 Request Example, 22 Response, 22 Response Example (OK), 23 Response Example (Unauthorized), 23
Logout, 24 Request Example, 24 Response Example (Error), 25 Response Example (OK), 24
M
Meta Model Endpoint, 21
Meta Model Object REST Web Services Interface, 14
N
NO CONTENT, 20
O
OK, 20
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 62 of 69
P
POST, 18
PUT, 18
R
Read All Meta Model Classes with Fields and Validators, 43 Request Example, 43 Response, 43 Response Example, 43
Read Domain Object, 33 Request Example (with Filter and Parameters), 34 Request Example (without Filter or Parameters), 33 Response, 34 Response Example, 35
Read Meta Model Class, Fields and Validators, 40 Request Example, 40 Response, 40 Response Example, 41
Read Meta Model Classes Domain Object API for Meta Model Access, 46 Request Example (with Filter and Parameters), 47 Request Example (without Filter or Parameters), 47 Response, 47 Response Example, 48
Read Meta Model Field Validators Domain Object API for Meta Model Access, 54 Request Example, 55 Response, 55 Response Example, 56
Read Meta Model Fields Domain Object API for Meta Model Access, 50 Request Example, 51 Response, 51 Response Example, 52
Re‐discover Meta Model Business Component API for Meta Model Discovery, 57 Request Example, 57 Response, 57
Related Documents, 6
REST Web Services Interfaces Overview, 11
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 63 of 69
S
Status Codes
200, 20 201, 20 204, 20 401, 20 403, 20 456, 20 500, 20 CREATED, 20 FORBIDDEN, 20 INTERNAL SERVER ERROR, 20 INVALID DATA, 20 NO CONTENT, 20 OK, 20 UNAUTHORIZED, 20
T
Typographical Conventions, 8
U
UNAUTHORIZED, 20
Update Domain Object, 37 Request Example, 37 Response, 38 Response Example, 38
W
Web Login, 26 Request Example, 26 Response, 26 Response Example (with Redirect), 27
Web Logout, 28 Request Example, 28 Response, 28 Response Example, 28
Web Verify, 30 Response, 30
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 64 of 69
Appendix A – Filter Operators
Note: For more detailed information on filters used in GUI, see the relevant Converge EMS filter documentation.
Below is an example of a filter that can be used in a request header in order to limit the number of objects returned in the response, or to point to exact instances of the desired objects. This filter returns only Meta Model objects for which the inherited attribute equals false.
Filters consist of the <filter> and <condition> tags that configure filter and condition objects, respectively. These tags can take the following attributes:
Field Example Description
operator (filter) <filter operator="and"> Defines logical relation between condition fields. When set to and, the results have to meet ALL conditions.
The example below returns all Meta Model objects with inherited field set to false AND the type field set to boolean.
<filter operator="and"><condition field="inherited"
operator="eq" value="false"/><condition field="type"
operator="eq" value="boolean"/></filter>
<filter operator="or"> Defines logical relation between condition fields. When set to or, the results have to meet ANY of the conditions.
The example below returns all Meta Model objects with inherited field set to false OR the type field set to boolean. For any returned object it is enough if either of the two conditions
<filter operator="and"><condition field="inherited" operator="eq"
value="false"/></filter>
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 65 of 69
has been met.
<filter operator="or"><condition field="inherited"
operator="eq" value="false"/><condition field="type"
operator="eq" value="boolean"/></filter>
<filter operator="not"> Defines logical relation between condition fields. When set to not, the results CANNOT meet any of the conditions.
The example below returns all Meta Model objects with inherited field set to any value other than false AND the type field set to any value other than boolean. Any returned object has the values of the two conditions different from the values provided in the condition.
<filter operator="not"><condition field="inherited"
operator="eq" value="false"/><condition field="type"
operator="eq" value="boolean"/></filter>
field (condition) field="inherited" Points to the name of a Meta Model Class field.
operator
(condition)
operator="eq" Defines the operator for the field value.
For example, eq is used to determine that the value of the field for the returned results has to equal the provided value.
Note: See next table for a description, examples and specific syntax for each operator.
value (condition) value="false" Defines the value for the field.
Table 22: Filter Structure
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 66 of 69
The following is a list of available filter operators (ordered alphabetically):
Warning: Most API operators are case-sensitive unless specifically stated otherwise in any description.
Field Description
allEq Used to search for all values equal to the range of values provided by the user. It matches multiple values.
begins Used to search for instances where the value of the given attribute starts with the value provided by the user.
between This operator takes two values
Used to search for instances where the value of the given attribute fits between the two values provided by the user.
contains Used to search for instances where the value of the given attribute contains the value provided by the user.
ends Used to search for instances where the value of the given attribute ends with the value provided by the user.
eq (equals) Used to search for instances for which the given attribute exactly matches the value provided by the user.
eqField (equals to
field)
Used to search for instances where the values of two provided attributes are the same.
ge (greater than or
equal to)
Used to search for instances where the value of the given attribute is greater than or equal to the value provided by the user.
geField (greater
than or equal to
field)
Used to search for instances where the values of the first is greater than or equal to the value of the second attribute.
gt (greater than) Used to search for instances where the value of the given attribute is greater than the value provided by the user.
gtField (greater
than field)
Used to search for instances where the values of the first is greater than the value of the second attribute.
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 67 of 69
iEquals Case insensitive operator
Used to search for instances where the value of the given attribute is anything different than the value provided by the user.
in This operator takes n values
iNotEquals Case insensitive operator
Used to search for instances for which the given attribute exactly matches the value provided by the user.
inSet Used to search for instances where the value of the given attribute is the same as one of the listed values.
isEmpty Used to search for instances where the value of the given attribute is set to empty.
isNotEmpty Used to search for instances where the value of the given attribute is set to any value other than empty.
isNotNull Used to search for instances where the value of the given attribute is not null.
isNull Used to search for instances where the value of the given attribute is null.
le (less than or
equal to)
Used to search for instances where the value of the given attribute is smaller than or equal to the provided value.
leField (less than or
equal to field)
Used to search for instances where the value of the first attribute is smaller than or equal to the value of the second attribute.
lt (less than) Used to search for instances where the value of the given attribute is smaller than the provided value.
ltField (less than
field)
Used to search for instances where the value of the first attribute is smaller than the value of the second attribute.
ne (not equals) Used to search for instances where the value of the given attribute is anything different than the value provided by the user.
neField (not equals Used to search for instances where the values of two provided
to field) attributes are different from each other.
notInSet Used to search for instances where the value of the given attribute is anything different from one of the listed values.
Table 23: List of Filter Operators
Transition Networks ConvergeTM EMS API Guide for Common RESTful API
33619 Rev. A www.transition.com Page 69 of 69
Transition Networks
10900 Red Circle Drive
Minnetonka, MN 55343 USA
Tel: 952- 941-7600 or 1-800-526-9267
Fax: 952-941-2322
Copyright© 2015 Transition Networks
All rights reserved.
Printed in the U.S.A.
Converge™ EMS API Guide for Common RESTful API Software Version 1.3.0 PN 33619 Rev. A