Despite all the recent hoopla, API’s have been around for a long time. Without realizing it, we use API’s all the time: we use them when we make an airline reservation…we use them when we check the weather on our phones. API’s bridge together several moving parts to serve up a desired result to the end-user. In the context of IT visualization software, such as DCIM or network documentation, they perform an important function: to integrate disparate systems and unify an organization’s data.
Unfortunately, not all API’s are built with the same level of quality and usability. If you’re considering purchasing IT visualization software, it’s a good idea to get an understanding of what API’s are and how they can work in IT visualization software (we use netTerrain as an example here) so that you don’t end up stuck somewhere down the road.
What is an API?
API stands for Application Programming Interface: simply put, it’s an intermediary that allows two software applications to converse.
To boil it down neatly, here’s an example I read on Mulesoft:
When you sit down at a restaurant to order a meal, you are the ‘end-user’.
The kitchen, which will prepare your meal, is the ‘system’.
The goal is for you to get the meal you want.
A server comes and takes your order. You choose what you’d like, and tell the server, “Atlantic Salmon seasoned with herbs. No salad, please.” Your server hands off your order to the kitchen staff in the most efficient form and language possible: as a ticket, written in shorthand. Your ticket will read something like this: “At. salm. H. 86 Salad.”
The ticket is given to the expediter, who decides where it should go next. It may first go to the executive chef, then the sous chef, then the fish chef, then a station chef and so on. As the ticket is written in restaurant shorthand, it’s easy for everyone working to understand, regardless of a chef’s language.
The server, and the ticket, serve an important purpose. If you were to go rogue and just walk back into the kitchen to order, you wouldn’t get very far. You wouldn’t know who is in charge of what…and you may encounter language barriers.
You get the point, right? Your server is the API, she or he takes your order (a message from you) and in return you get the food (the response from the system).
Pretty cool stuff…if you can use that to your advantage.
What are API’s used for?
With netTerrain, you can use our API to do a bunch of different things, automatically, from an external application:
- Read the contents of a network diagram
- Create nodes and links or cables in DCIM
- Move nodes and links around, using your own algorithms
- Read DCIM device, rack, cable, and other data
- Manage the netTerrain catalog from an external app
- Manage users and groups automatically based on rules imposed by some other corporate system instead of having to manage them manually from within netTerrain
- Create your own custom menus in netTerrain to do something
- Assign your own double click behaviors
- and much more
The netTerrain API’s are available for all of users — regardless of whether you use netTerrain for network mapping, Data Center Infrastructure Management, or Outside Plant — and we don’t charge for them (I can’t understand why so many DCIM and network documentation vendors tack on extra fees for access).
What does netTerrain provide in terms of API?
While we won’t delve into the details of what a REST-compliant Web service is (plenty of material on the web about that), it’s worth noting that many vendors claim their API’s are “RESTful”…but when you look under the hood and they are anything but. The truth is that many DCIM vendors offer problematic API’s that are obsolete, non-standard, and come with bare-bones documentation (that is, if they even offer API’s).
We have not just one, but two, API interfaces (which happen to be the de-facto industry standards nowadays for so-called Web-services: SOAP and REST). These standards are more like guidelines, however: there is not necessarily a strict enforcement on how web-services should be designed.
As a company, we are obsessed with security, usability, and flexibility, so: we are a bit obsessed with making our API’s hyper secure, easy-to-use, and very extensible.
In short, our API’s are modern:
- Secure
- Properly documented
- They are abstracted in its own “layer”
- They follow certain standards (RESTful, for example)
With netTerrain, you may be able to do many of the things you could do with the netTerrain API’s by tapping into the backend of our database or by using our integration toolkit (ITK). There are, however, certain advantages to using our API:
* It is asynchronous in nature: as opposed to the ITK, which polls data from a source in a synchronous fashion or upon manual triggering, you can push data asynchronously into netTerrain. This could be a better alternative for certain real-time applications, or to reduce the number of processes used to update data in netTerrain
* It is database structure independent: using the API for data extraction or reporting purposes
To sum up: the API is for grown-ups!
SOAP vs. REST
Generally speaking, these services have advantages and disadvantages: REST relies on http; SOAP doesn’t necessarily rely on http.
In theory, REST tends to be easier. SOAP has built-in error handling and is supposed to work better in a distributed environment. For example, when you use SOAP in netTerrain, SOAP requires you to create an application in some development environment, such as Visual Studio. It requires compliance with the WCF. Users of the API are typically programmers familiar with C# (or Java or Python or whatever you get your hands on that is able to connect to WCF). Within your environment, you then reference our SOAP API, which exposes all classes and methods.
Now, if you aren’t familiar with any of these vastly superior OO languages and all you did was write some spaghetti PHP scripts or hack some SQL: you are still welcome, we forgive you (but you may just be better off using the REST interface).
Long story short: our REST API is easier. For starters, you can access the documentation directly from our swagger hook, which — starting in version 7.1 — is available directly from our help menu. From there, you can even test a REST call and play around. To write your own app, you can use any REST client you want and setting this up is a lot easier because there is a lot less housekeeping needed (see above) to get started.
Where can I learn more?
Our SOAP documentation is available from the admin console help menu, in both netTerrain and in our customer portal. Throughout the guide, we use C# as our reference language. This does not mean that the netTerrain SOAP API is language specific. In the API reference guide, we review each method that is exposed through the API interface including the syntax, exceptions, remarks, and an example.
As I mentioned earlier, you can access the documentation directly from our swagger hook, which starting in version 7.1 is available directly from our help menu.
In subsequent blogs, we’ll be discussing setting up SOAP, and REST, in more detail. In the meantime, go get a coffee and start churning out some lines of code.