etapAPI™

etapAPI – Connect Remotely to ETAP as a Service

etapAPI is ETAP's public-facing RESTful API and can be consumed from any language on any device. The device can be the computer ETAP runs on or another device on the same network. etapAPI enables interoperability with ETAP, which allows automation, scripting, and remote studies as a service to callers.

The etapAPI is a RESTful service that runs inside DataHub™, which is ETAP’s gateway for all data exchanges and is used by ETAP and third-party tools via a secure connections (https). While DataHub hosts various services (internal and public), etapAPI is the service mostly used by ETAP customers.

The etapAPI is divided into five major sections: Application, DNP3 Server, Project Data, Studies, and Scenario. These sections can all be explored via the Swagger page, which enables users to see and interact with the etapAPI without having to write client code, and is entirely browser based. The Swagger page allows user to experiment and see features offered in etapAPI.

Application Section

This section contains calls about the ETAP application. For example, in this section it is possible to retrieve both user name and project name.

DNP3 Server

This section contains calls relating to DNP3 communication. DataHub hosts a DNP3 server, which the user may initiate and interact with from the Swagger page. For example, one can start the DNP3 server with sample settings and then update server data such as inputs and outputs. Additionally, the server may be interfaced with external DNP3 client devices.

Studies Section

This section contains calls to perform studies. For example, one can request that ETAP run a load flow study from the Swagger page.

Project Data

This section contains calls that return project data. For example, one can request to view all bus elements or get parameters for elements by type. Users can also modify project data for example create/delete elements, modify element properties for power ratings, element name, service state, and enter study case settings for iterations, precision, simulation time.

Scenario Wizard

This section contains calls that allow interacting with the ETAP Scenario Wizard. With ETAP Scenario Wizard one can trigger pre-configured studies remotely and invoke UI updates.

Networked Environment

etapAPI offers endpoints for public consumption. When in a networked environment, a single client can access many ETAP instances. Each instance continues to function as normal to its local user, but it also becomes a service to remote users.

To enable this feature, users can write their own REST client or use etapPY API which is our client-ready approach to consuming the etapAPI.

ETAP in networked environments gives rise to parallelism when running studies. It also gives rise to test automation. For example, a single client can command different ETAP instances to perform studies and return the results to a central location for comparison. One could then repeat the execution and even scale to batch studies over the network.

How can Software Communicate with ETAP

Each instance of ETAP exposes a dedicated REST API for public consumption over secure http (https). One machine can run several ETAP instances (one per project) or one instance of ETAP can be commissioned on a per-machine basis. The latter is better suited for a large volume of parallel workloads (e.g. running a large number of studies in parallel).

Callers can call ETAP from any REST-compatible client. Some of the clients we currently work with:

C/C++
C#
cURL
Go

Java
Javascript
Nodejs
PHP

Python
Ruby
Shell
Swift

SOAP Support

Historically ETAP supported SOAP services through WCF WSDL files as the backend. These services are being migrated toward the more interoperable alternative (REST). Therefore, while ETAP currently supports SOAP services, these will be deprecated soon.

API Organization

ETAP's REST API is organized into sections as summarized by the table below.

What is a RESTful API

REST is an acronym for Representational State Transfer. It is an architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his dissertation.

Representational state transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style, called RESTful Web services, provide interoperability between computer systems on the internet. RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations. Other types of Web services, such as SOAP Web services, expose their own arbitrary sets of operations.