Ultimate Guide to the Micetro REST API

How can you get started automating workflows including your DNS, DHCP, and IPAM services? The best way is just to dive into the the REST APIs of your DDI network management solution.

Importance of REST APIs for DDI

DNS, DHCP, and IPAM are some of those common services that are critical to implementation, uptime, and performance of an application, but may often not always have dedicated engineers and architects to design and maintain them. These DDI services are often decentralized throughout your infrastructure, perhaps running native services often in the cloud and then running Microsoft or ISC on-premises, as just a few examples, though there are many more services out there.

While it's important to be able to run these types of services, because likely they're the best services for whatever platform you're choosing to run your workloads, you can see that even if you were creating automation workflows, this becomes very complex. For example, you'd have to create a workflow using Microsoft DNS or DHCP on-premises, a different workflow for AWS, a different workflow for Azure, and the list goes on.

The beauty of using a software DDI overlay is that you can continue to use the appropriate and performant services, but you have one place to go to manage access control, manage DDI objects, and of course create consistent automation workflows with the use of one REST API. Now, using this one API, we can use the same workflow for workloads in the cloud as we're using for workloads on-premises. Even if we change those underlying services to more suitable services in the future, we can continue to use those same workflows!

What is an API?

API stands for Application Programming Interface. Essentially it offers the objects within a certain solution to developers and other software solutions so that they may view and manipulate the objects through code rather than through another interface such as the CLI (command line interface) or GUI (graphical user interface).

My favorite metaphor for describing an API is that it's like the menu at a restaurant. If the restaurant is open to the public then any customer may go in and order off the menu. The chef then cooks the item according to their style, sometimes with specifications from the customer, and the customer then receives the cooked food.

APIs may not be available to the public for all software solutions. Sometimes companies will only allow external users access to some of the APIs but not all. If being able to create workflows for everything available within a solution through the APIs is important to you, then you should definitely inquire whether all APIs are available before purchasing a new DDI solution.

What is REST?

REST stands for REpresentational State Transfer. REST gives us a common language so that communication between developers and software, or software solutions and other software solutions, is possible. REST provides a particular format in which messages can be sent between two machines. There are other examples out there such as SOAP (Simple Object Access Protocol), but REST has become very popular and is often referred to as the "language of the Internet."

Therefore a REST API is an interface which uses the REST protocol or language to send and receive messages, or code, between two software solutions or between a developer and solution. The REST API documentation tells you which objects are available and what actions you may take.

Micetro REST API

In order to get to the Micetro REST API you do have to install Men&Mice Web Services but then you can access the API documentation by going to  the following URL:

http://< machine you have installed the services >/mmws/api/doc

Once you've navigated to the URL you'll see something similar to the above image. Here you may toggle certain categories so that you can see all of the actions and specific objects available on the "menu."

CRUD Actions

The available actions available in most APIs are referred to as CRUD actions, Create, Read, Update, and Delete. CRUD is a widely used acronym throughout the IT industry, not just when referring to APIs. In the case of this REST API, though, the POST action is how you create a new object, the GET action is how you read information from an object, the PUT action is how you update an object, and the Delete action is how you Delete an object.

How Does it Work?

Now in order to manipulate or read an object we need a minimum of two things

1. Which action to perform
2. Location of object

The location of the object will be a URL (Uniform Resource Location), much like what you see in your browser when you navigate to a specific page. The action will be one of the CRUD actions described above. We can find the URL using the API documentation. For example, if I want to obtain all of the AD Forests within the Micetro environment, I would use the URL:

http://<Micetro web services >/mmws/api/ADForests

I found this in the API documentation here:

As you can see from the URL, I've appended /ADForests as indicated in the above image to the original API URL of http://<Micetro web services>/mmws/api

You can actually put this URL in a browser and it will return the information you are asking for, in this case AD Forest information, on the browser page as long as you have access and there are no other required parameters.

Sometimes there is a third requirement of parameters input by the user. For example if you're trying to create a new DNS record. Before we get to an example of using POST, though, let's talk about how Swagger is built-in to the Micetro API documentation.

What is Swagger?

Swagger is an Interface Description Language used in REST APIs. If you're familiar at all with Postman, from Google, it's very similar. Swagger allows you to simply try out API call and response right there within the documentation before you start implementing the calls within your larger workflows. Let's explore how Swagger works through the example of adding a DNS record programmatically through the API.

First we'll scroll to DNS Records and toggle that so we can see what's available on the menu under this category.

At the top of this we see the Response Class section, but let's go down to what's in the Parameters section first. The body is what you'll need to fill out in order to create a new DNS record programmatically. This may look intimidating, but we actually just need to copy and paste the model schema provided for us on the right under Data Type. Just clicking in that box will copy and paste this automatically. Now you can click on the word Model to get the definitions of these values.

In the body all we have to do is fill out some of the information now. You can see below that I've just left "string" next to the "ref" value.  I've filled in the name of my DNS record to be "micetro-autotest," it's a TXT DNS record, the TTL is 3600, and I've put "Testing for POST" in the data field. If this were an A record, the IP address would go in the data field, just as another example. I've enabled the DNS record and I've specified that it will be in the micetroautomation.net DNS zone. I've "nilled" some of the other values and completely deleted others that weren't required.

{
"dnsRecords": [
{
"ref": "string",
"name": "micetro-autotest",
"type": "TXT",
"ttl": "3600",
"data": "Testing for POST",
"comment": "",
"enabled": true,
"aging": 0,
"dnsZoneRef": "micetroautomation.net.",
"customProperties": {"key": ""}
}
`],
"saveComment": "",
"dnsZoneRef": "micetroautomation.net."
"forceOverrideOfNamingConflictCheck": false
}

Now, when we click "Try it out" we should get a 201 under Response Code if we are successful. This means that we successfully created this DNS record.

Testing it Out

We can test this out in a couple of ways. 201 means I'm successful, but we can make sure by now using the GET DNS record in the API and using Swagger.

We can also just jump in the Micetro Web UI and see that we now have a record there.

Using APIs in the Real World

Likely you're not going to be popping in to the the Micetro API documentation and using Swagger to add one DNS record at a time. You may choose to use Ansible, Terraform, Powershell, customer scripting, or even a third party tool like ServiceNow to create workflows. You may also use the APIs for monitoring your DDI environment with solutions like PRTG. Using Swagger in the API documentation is a great way to get started learning how the API works, though.

We'd love to hear from you! How do you want to use the APIs? What workflows are you planning, such as creating IP range templates, onboarding new services with self-service portals, or sunsetting services and reclaiming IP address? Let us know what you'd like to hear more about!