If you’ve seen any of our other posts on TOP Server V6 and its new capabilities, you may have seen us mention the Configuration API. Unless you’re a developer, you may have been wondering what is that and why would I care? We’ve been pleasantly surprised by how many of our users have had an interest in this new feature.
So, first, what is an API? The term API stands for Application Programming Interface. In simple terms in the context of what we’ve released, an API provides a set of building blocks for a developer to write software that connects to another software program and lets your software interact with the TOP server. Technically speaking, the OPC interfaces in TOP Server used for getting real time data could be considered API’s.
In this case, the Configuration API is a set of building blocks, or functions, for creating and updating the TOP Server’s configuration from another program, instead of from our configuration user interface that you’ve known for years. So the Configuration API is about the setup of the product, not about collecting real time data. For real time data, you’ll still use OPC, Suitelink, or the other real-time interfaces in TOP Server.
Why do you care about an API?
Whether this matters to you or not really depends on how you use TOP Server, who your users are that might need to interact with the product’s configuration interface, what other software applications that are part of your automation stack, the size of your projects, and how often they change.
What we’ve heard over the years from our users, integrators, partners, and OEMs is they had situations where they didn’t want to provide the full configuration user experience to their users, or the scale of their applications was so large, that they needed alternative ways to configure and integrate the offering into their software stack. Our large community of Wonderware System Platform power users and integrators have expressed a desire for a way to configure TOP Server from within their offering.
Heard enough and ready to talk to somebody about your needs?
Some examples that might get you thinking about your applications include:
- Enterprise Users with large projects that are changing constantly, such as in upstream oil & gas where assets are constantly being added and removed or moved.
- Enterprise Users with other software applications, including in-house applications or other configuration tools they would prefer to use to manage the TOP Server configuration and maintenance process.
- Machine builders seeking to automate changing of machine configurations across different customers or markets.
- System Integrators seeking to reduce engineering cost through automation of routine, repetitive configuration tasks.
- System integrators seeking to offer their users limited and simple access to certain routine configuration actions.
- Users that need to limit what certain users can do beyond the capabilities of the built-in TOP Server User Manager and want to limit even what the user can see, or present the configuration information in alternative formats that are more meaningful to their users.
The Config API is full of CRUD!
For you developers out there, yes, this means full CRUD operations! For you non-developers, CRUD stands for CReate Update Delete. The TOP Server V6.0 Configuration API allows you to read, create, update, and delete channels, devices, groups, meter groups, and tags. Over time, the various optional plug-ins will also be configurable via the API.
This means you could write a program in the programming language of your choice, on the platform of your choice, and use that to configure your TOP Server. This may sound scary, but that’s also why security is baked into the offering as you’ll see a little further below.
The standard Configuration API is implemented as a RESTful web service that is built into TOP Server Version 6.0 and higher and is included in all license purchases. Experienced developers will automatically know what that means but I like to make my posts include helpful learning for all audiences as well.
So for non-developers reading today, don’t let the term “web service” scare you. The word “web” does NOT mean that you have to expose your TOP Server to the internet to take advantage of the Configuration API! It’s just the term that someone out there in the software industry came up with to describe the technology. Think of a web service as a way to connect to the TOP Server using http: or https: secure connections, and make function calls to do the configuration work.
Example: https://localhost:57418/config/v1/project/channels
The above is an example of a web service endpoint that, when called while including the appropriate authentication, will return a list of all the channels in your TOP server project. Note that you could replace “localhost” with the IP address of a TOP Server on your internal network and remotely configure a TOP Server!
The developer’s code actually points at the web service like it’s calling up a web page! For them it’s easy to understand, works well across many platforms, and doesn’t involve any complicated networking.
Tired of reading? Ready to talk to someone about your application?
Configuration API Security
Just like powerful woodworking tools, you need to wear your safety gear and not remove the safeties on your tools. To that end, out of the box, it was important for the Configuration API to be secure and to integrate with other security features built into the product such as the user manager that lets you setup user logins and control what they can do, even blocking them from deleting anything.
Here’s a short list of features that address security:
- API is Disabled by default
- HTTPS endpoint support
- HTTP endpoint disabled by default
- SSL certificate support
- Filtering by source domain
- HTTP/HTTPS basic authentication
- Integrated with TOP Server User Manager and Security Policies Plug-In for granular rights control
- Transaction logging with configurable levels of verbosity and retention with API access to the transaction log
Developer Speak Warning! Other Key RESTful API Features
- Full Create, Update, and Delete operations (CRUD) on:
- Channels
- Devices
- Tag Groups
- Meter Groups (specific drivers)
- Tags
- Aliases
- Channels
- Object definition using JSON data format
- Built-in documentation describiing the endpoints and valid configuration properties
- Support for all drivers (some limitations may apply)
- Support for the following plug-ins with V6.0 (more to come in future releases):
- Media-Level Redundancy
- Scheduler
- Media-Level Redundancy
.NET Configuration API
Coming soon. Recognizing that many of our users are .NET developers, especially our Wonderware System Platform users, Software Toolbox will be offering an object-oriented .NET wrapper for the RESTful API for users who develop in Visual Studio.NET and do not want to have to handle the management of the calls to the RESTful web service and serializing and de-serializing of the JSON packets.
The goal is to provide these developers a rapid development environment that allows them to focus on the configuration tasks, not the plumbing of implementation of the API.
Key .NET API Features
- Single .NET namespace consumable in Winforms, WPF Forms, Console, Service, and ASP.NET applications or applications supporting .NET Framework 4.0 or higher.
- Object-oriented operation treating configuration items as objects: channel, device, tag group, meter group and tags.
- Complete management of the web service connection and serializing, de-serializing of the JSON messages and objects.
- Simplified command set designed to reduce development time.
We are currently working to get to an early Beta on this offering. If you’re interested in learning more, please contact us to discuss your application and to be considered for our beta program.
