Engine Management Service API

Summary 

This knowledgebase article provides information about Engine Management Service (EMS) API:

1. frequently used API endpoints (applicable to all supported CE versions)
   
2. procedure for enabling, capturing and viewing Swagger API documentation (valid starting with CE v16)

EMS frequently used API endpoints

Root-endpoint

https://<ems-address>:9727

1. all of the following API endpoints are relative to this root.

Authorization

Basic authentication

1. EMS username and password

Determine active node in Engine cluster

GET /hbws/v1/serverlist

• drill down in serverlist response for your server clusterName. Locate serverChain property and search for the node server identity having role: "ACTIVE". (Identity value may be PRIMARY, SECONDARY, TERTIARY)
• sample response
  • {
"gen": 1729084656072,
"mgmtServerId": "lj-2k19-ems-4Z6CLQTV",
"serverList": [
{
"groupType": "TERNARY",
"isActivePartition": true,
"lastError": {
"id": "",
"detail": ""
},
"hostOS": "WINDOWS",
"serverChain": [
{
"server": "PRIMARY",
"fileSystem": "SYNCHRONIZED",
"registry": "SYNCHRONIZED",
"role": "ACTIVE",
[...]

Determine filesystem status (synchronized or not) in Engine cluster

GET /hbws/v1/serverlist

• drill down in serverlist response for your server clusterName. Locate serverChain property and search for the property fileSystem. Should be "SYNCHRONIZED" for each node in serverChain.
• sample response
  • {
"gen": 1729084656072,
"mgmtServerId": "lj-2k19-ems-4Z6CLQTV",
"serverList": [
{
"groupType": "TERNARY",
"isActivePartition": true,
"lastError": {
"id": "",
"detail": ""
},
"hostOS": "WINDOWS",
"serverChain": [
{
"server": "PRIMARY",
"fileSystem": "SYNCHRONIZED",
"registry": "SYNCHRONIZED",
"role": "ACTIVE",
[...]

Make Primary Active

POST /hbws/v2/server/<engine-server-name>/plan/makeactive

Request payload:

{

      "keepSync":true,

      "newActive":"PRIMARY"

}

Start Replication

POST /hbws/v2/server/<engine-server-name>/plan/startreplication

Request payload: (default, ensuring the apps are running)

{

      "startApplications":true

}

Stop Replication

POST /hbws/v2/server/<engine-server-name>/plan/stopreplication

Request payload: (default, with leaving applications running)

{

      "stopApplications": false

}

Start Applications

POST /hbws/v4/server/<engine-server-name>/applications/start

Request payload:

{}

Stop Applications

POST /hbws/v4/server/<engine-server-name>/applications/stop

Request payload

{}

Configure Orphaned File Detection and Action

POST <engine-management-server>:9727/hbws/v4/server/<engine-server-name-as-in-ems>/data/FileStateMgr

Request payload:
{

"autoDeletes":{"PRIMARY":true,"SECONDARY":true,"TERTIARY":true},

"autoDeleteAction":1,

"doFastCheck":true,

"fastCheckTimeout":60000

}

"autoDeleteAction":1 - means delete action

"autoDeleteAction":0 - means log to file (don't delete)

Start Orphaned File Check

POST <engine-management-server>:9727/hbws/v4/server/<engine-server-name-as-in-ems>/data/orphanedfilescheck

Request payload:

1. for checking orphan files on first passive (SECONDARY)
   
1. {"server":"PRIMARY"}

1. for checking orphan files on second passive (TERTIARY)
   
1. {"server":"SECONDARY"}

Enable/Disable Inclusion File Filter

POST /hbws/v4/server/<engine-server-name>/filters/inclusion/edit

e.g. Following paylod disables System's plugin C:\PROGRAMDATA\NEVERFAIL-PROTECTED\** inclusion file filter: 

Recommendation: exercise this via EMS UI and check the API details for better understanding.

Request payload:

{

      "newPattern":"C:\\PROGRAMDATA\\NEVERFAIL-PROTECTED\\**",

      "enabled":false,

      "oldPattern":"C:\\PROGRAMDATA\\NEVERFAIL-PROTECTED\\**",

      "sponsor":"System"

}

Get protected services

GET /hbws/v1/server/<engine-server-name>/services

1. in response under services there are listed all the protected plus dependent services and their corresponding configuration.
   
1. actualState - indicates service status on the mentioned node [Primary, Secondary, Tertiary]
   
2. sponsors - indicates the name of the plugin(s) protecting the service
   
3. e.g. in the below sample, lanmanserver: is protected, managed, monitored by FileServer plugin and running on Primary which is currently active server  
   
4. "services": {           
   
         "PRIMARY": [
   
               {
                   "originalStartupType": "Automatic",
                   "displayName": "Server",
                   "originalState": "Running",
                   "actualState": "Running",
                   "targetStateActive": "Restarted",
                   "onSecondFailure": "Heartbeat\\Recover Service",
                   "isManaged": true,
                   "onThirdFailure": "Heartbeat\\Recover Service",
                   "isProtected": true,
                   "useExtendedRecovery": false,
                   "sponsors": [
                       "FileServer"
                   ],
                   "name": "LANMANSERVER",
                   "targetStatePassive": "Running",
                   "isMonitored": true,
                   "onFirstFailure": "Heartbeat\\Recover Service",
                   "failureCount": 0
               },

 

Procedure for enabling, capturing and viewing (Swagger) EMS API documentation

This procedure is valid starting with CE v16.

Starting configuration:

1. By default, after CE installation, EMS API documentation is disabled.
   
2. Initial APIs are empty only declarations, and in this form they are not interpreted/displayed in Swagger Editor. As the APIs get called, their properties (description, parameters, response codes, etc.) are captured in Swagger format.

Enable API documentation

1. In  EMS registry, go HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Prefs\nfwebsvcs\management\nfmgtwebsvc and edit the value documentation_enabled = true
   
2. Restart Neverfail Engine Management Web Services

Capture API definition

1. using EMS UI, exercise the action/API you intend to document
   
2. GET collected EMS API documentation*
   
1. GET https://<ems-address>:9727/hbws//v6/server/localhost/documentation

   Response contains collected API documentation.
   

   This may be loaded to Swagger Editor for more user-friendly view.
   *not all APIs are collected. Contact Neverfail Support for guidance.
   

View API documentation in Swagger

1. load collected API documentation in Swagger Editor. 

Applies to

Neverfail Continuity Engine Management Service v16 and beyond

• Related Articles

• How to enable HTTP Strict-Transport-Security (HSTS) in Continuity Engine Management Service

  Summary This Knowledgebase article provides information about how to enable HTTP Strict-Transport-Security (HSTS) in Continuity Engine Management Service The HTTP HSTS is a mechanism that allows websites to declare that they can be only accessed via ...

• Engine Management Service (EMS) FAQ

  What is EMS (Engine Management Service)? The Engine Management Service is the primary tool used for deployment and normal daily control of Neverfail Continuity Engine. Most routine operations can be performed from the Engine Management Service User ...

• How to enable DEBUG level logging on Neverfail Continuity Engine Management Service

  Summary  This Knowledgebase article provides information about how to enable DEBUG level logging on Neverfail Continuity Engine Management Service. Procedure To enable DEBUG level logging on Neverfail Continuity Engine Management Service: On the ...

• Welcome to Continuity Engine 16 - What's New

  Continuity Engine 16 This release supersedes Continuity Engine v15. What's New EMS Alerting based on Managed Server Telemetry The first chapter in unlocking advanced monitoring and alerting is to enable our new telemetry service, which will ...

• Neverfail Continuity Engine 16 Release Notes

  Summary The following information applies to the v16 release of Continuity Engine. Continuity Engine 16 This release supersedes Continuity Engine v15. What's New EMS Alerting based on Managed Server Telemetry The first chapter in unlocking advanced ...