Articles
Lauren Malhoit

DDI Automation with Swagger

Testing out the Micetro APIs

Apr 14th, 2022

Automating DNS, DHCP, and IP tasks can help you create a more consistent and reliable network, but getting started with automation can be overwhelming. At Men&Mice we want to make it simple to get started.

Getting Started with the Micetro APIs

If you'd prefer to watch the video instead of read the blog, check out the video below. The below video also briefly describes the Micetro solution, DNS Records, and shows the Web UI. For the sake of blog length we'll just keep it to an API discussion here, though.

I'd first like to point out that anything you can do in the Micetro management console or web UI can also be done via the APIs, which means that you can do anything in the Micetro environment programmatically. What we're going to walk through here in this blog (and in the video above) is how to use the Micetro REST API documentation to learn more about getting information about our environment.

Generally, when we 're talking about APIs, we're talking about software talking to each other through APIs. For the sake of learning, though, we're going to be doing some manual things to better understand how this works so that we can then build upon that to create larger automated workflows. Eventually we'll be able to create workflows offered from self-service portals which will allow people to onboard entire services, sunset services, and create reports, just as an example.

So first, let's jump into the Micetro API by going to the URL on our browser and then appending it with /mmws/api/doc. Here we'll see all of the possible areas we can perform actions on within the API and get some information on what the software needs to perform the actions.

MIcetro REST API Documentation

CRUD

You can use CRUD (Create, Read, Update, and Delete) actions to perform any action using an API call. You'll notice in the image above you'll see the possible actions on the left with POST in green, GET in blue, PUT in brown (or amber?), and Delete in Red.

Create = POST

Read = GET

Update = PUT

Delete = DELETE

In this blog we're just going to concentrate on GET, so we'll be reading some DNS record information.

Swagger

Men&Mice builds Swagger into the backend of our API documentation. This means that you can actually try things out within the documentation. This is very handy for learning and testing tasks out, but in the real world of automation we'll likely be using solutions like Ansible, PowerShell, or even ServiceNow to run automation workflows.

Let's go ahead and expand GET /DNSRecords/{dnsRecordRef} to get started retrieving and understanding a DNS Record.

GET /DNSRecords/{dnsRecordRef} in the API doc using Swagger

If we analyze this image from the top down, we see the Response class, with Model schema highlighted. In the yellow box it's showing us what we'll see as the response once we make the GET call to our APIs. For example, within the dnsRecord we'll see the "data" object of the record, which be a "string" type that will tell us what's in the value field of the DNS record. For example, if it's an A record, the data will be an IP address.

If we click on "Model" we'll get to see definitions of each of these objects to gain a better understanding of what will be returned in the response.

Clicking on Model to see object definitions

Below that we see that we can choose the Response content type, which will either be application/json or application/xml. We'll stick with JSON for now because it's more human readable.

Call and Response

In this example, we are required to input a parameter in order to get a proper response. The parameter required here will either be the DNS record name or reference number. So we'll type in "test-automation" because I know that I have an A record called "test-automation" in my Micetro environment and that's the record I need information about.

Then I'll go ahead and click on Try it out!

After clicking Try it out!

I now have a Request URL: http://ddi.sm.mmdemo.net/mmws/api/DNSRecords/test-automation. If you're at all familiar with Postman, Swagger is really similar to Postman, and this is the URL you'd use within Postman to get this same information. You can even copy this URL and just paste it in your browser to get the same information as see in the Response body! Basically what happened is that it took my API URL and appended it with "DNSRecords" because that's the object I'm working within and "test-automation" because that's the parameter I typed in.

In the Response body we can now see all the information we wanted to know about that DNS record. Now, even though this isn't necessarily an automated workflow that helps you onboard a new service, this is certainly the start to being able to do such a thing!

The Response Code

You'll notice at the bottom of the image above we see a response code of 200. This means my call was successful. You can search for a whole list of API status codes, but just a few worth remembering are:

200 = OK

400 = Bad Request

404 = Forbidden

We can see an example of when we get a 400 error when we type in a DNS record name that may be used several times in the Micetro environment, such as the name "test" in my environment.

Response Code 400 - Bad Request

In the Response body we can even see a message that tells us why we got a 400 error, which is "Specified DNS record name matches multiple DNS records."

Give it a try!

Now that we've played around in Swagger a bit, go ahead and see what GET actions you can perform in other areas of the API. If you don't have Micetro, you can download a free trial to get started. If you have any questions about installing or suggestions for what we should show in future automation blogs and videos let us know!