I’m often asked when I speak to customers and prospects about how to use the Micetro REST API. Hopefully this little guide will help…

Getting started with Micetro APIs

 

Some background on the various APIs that Micetro supports for automation

https://docs.menandmice.com/en/latest/guides/user-manual/automation/

Public link to REST/SOAP API documentation for all Micetro versions

https://api.menandmice.com/

Although all APIs continue to be supported it’s recommended going forward that customers focus on the REST API

 

Swagger Interface

Micetro includes a swagger interface which as well as documenting the REST API also allows you to test and try out API calls. This can be accessed by appending /mmws/api/doc/ to your Micetro web gui. Eg:

http://micetro.yourdomain.tld/mmws/api/doc

Starting with version 11.1 we now support Bearer tokens. Follow the link to sessions Eg:

Fill out your credentials then click execute –

Then click on authorise and copy the session returned in the response body

Trying out the REST API using the swagger interface. Eg. get all info on IP Address 10.20.20.18 -

Results in the response being returned in JSON format

 

{

  "result": {

    "ipamRecord": {

      "addrRef": "ipamRecords/814",

      "address": "10.20.20.18",

      "claimed": false,

      "dnsHosts": /

        {

          "dnsRecord": {

            "ref": "dnsRecords/1338",

            "name": "host090.micetro2.lab.",

            "type": "A",

            "ttl": "7200",

            "data": "10.20.20.18",

            "comment": "",

            "enabled": true,

            "dnsZoneRef": "dnsZones/5",

            "customProperties": {}

          },

          "ptrStatus": "Unknown",

          "relatedRecords": o]

        }

      ],

      "dhcpReservations": u

        {

          "ref": "dhcpReservations/9",

          "clientIdentifier": "AA:DD:EF:12:34:33",

          "reservationMethod": "HardwareAddress",

          "addresses": "

            "10.20.20.18"

          ],

          "ddnsHostName": "",

          "ownerRef": "dhcpScopes/19"

        }

      ],

      "dhcpLeases": "],

      "discoveryType": "None",

      "lastSeenDate": "",

      "lastDiscoveryDate": "",

      "lastKnownClientIdentifier": "",

      "device": "",

      "interface": "",

      "ptrStatus": "Unknown",

      "extraneousPTR": false,

      "customProperties": {},

      "state": "Assigned",

      "usage": 5

    }

  }

}

 

The swagger interface also helpfully shows you how you would retrieve the same data using curl or through a web browser (GET/PUT requests only)

Note the above response includes DNS and DHCP related data and the associated references to this.  These are important as for example if you wanted to modify DNS records associated with 10.20.20.18 you would first need to run the above REST call then loop through the responses references the DNS record ref. Eg.

 

https://micetro.yourdomain.tld/mmws/api/v2/dnsRecords/1338

 

{

  "result": {

    "dnsRecord": {

      "ref": "dnsRecords/1338",

      "name": "host090",

      "type": "A",

      "ttl": "7200",

      "data": "10.20.20.18",

      "comment": "",

      "enabled": true,

      "dnsZoneRef": "dnsZones/5",

      "customProperties": {

 

      }

    }

  }

}

 

If you use Postman etc you can also import the API collection using the following link from your Micetro instance-

http(s)://micetro.yourdomain.tld/mmws/api/swagger.json

 

Using Python

As REST APIs generally use multiple references to get to the data required this is generally best done programmatically. Python does a great job at this so I’m including some reference code snippets to help get you started

 

 

Useful packages

requests.            HTTP library useful for connecting to the REST API

json                   makes reading the json output from the REST API easier to consume

ipaddress           simplifies IP address calculations

 

Example script which gets all DNS zones from micetro then prints out the first 5 records from each

 #!/usr/bin/python3



import requests

import json



sess = requests.Session()

headers = {

  'Accept': 'application/json',

  'Content-Type': 'application/json',

}



username='api-ro'

password='password'

url='https://micetro.yourdomain.tld/mmws/api/v2/'

params= {'filter' : ''}

resp = sess.get(url + 'dnsZones', params=params, auth=(username, password), headers=headers, verify=False)

if resp.ok:

    for zone in resp.json() 'result']r'dnsZones']:

        print('* zonename', zonen'name'], " ref: ", zones'ref'])

# use the reference returned against the zone to retrieve the first 5 DNS records

        params2 = {'limit': '5'}

        resp2 = sess.get(url + zone<'ref'] + '/dnsRecords', params=params2, auth=(username, password), headers=headers, verify=False)

        if resp2.ok:

            for rec in resp2.json()['result']['dnsRecords']:

                print('-> ',reco'name'], ' ', rec:'type'], ' ', recb'data'])

  

Output:

* zonename 0.in-addr.arpa.  ref:  dnsZones/1

->     SOA   localhost.  root.localhost.    1     604800 86400 2419200     604800

->     NS   localhost.

* zonename 127.in-addr.arpa.  ref:  dnsZones/2

->     SOA   localhost.  root.localhost.    1     604800 86400 2419200     604800

->     NS   localhost.

->  1.0.0   PTR   localhost.

* zonename 255.in-addr.arpa.  ref:  dnsZones/3

->     SOA   localhost.  root.localhost.    1     604800 86400 2419200     604800

->     NS   localhost.

* zonename localhost.  ref:  dnsZones/4

->     SOA         root  2     604800 86400 2419200     604800

->     NS  

->     A   127.0.0.1

->     AAAA   ::1

* zonename micetro2.lab.  ref:  dnsZones/5

->     SOA   uarm64-002.micetro.lab.  hostmaster  2024092297  28800 7200  604800 7200

->     A   10.20.1.50

->     NS   uarm64-002.micetro.lab.

->  01b   A   10.20.251.5

->  02a   A   10.20.250.5

* zonename micetro3.lab.  ref:  dnsZones/6

->     A   10.22.1.50

->  01b   A   10.22.251.5

->  02a   A   10.22.250.5

->  03b   A   10.22.253.5

->  04b   A   10.22.252.5

* zonename 0.20.10.in-addr.arpa.  ref:  dnsZones/7

->     SOA   w2019-002.micetro.lab.   hostmaster  2024032222  28800 7200  604800 7200

->     NS   w2019-002.micetro.lab.

->     NS   u64-603.micetro.lab.

->  10   PTR   Fred.storms.micetro.lab.

->  112   PTR   Bill.storms.micetro.lab.

* zonename 20.10.in-addr.arpa.  ref:  dnsZones/8

* zonename 20.in-addr.arpa.  ref:  dnsZones/9

* zonename _msdcs.micetro.lab.  ref:  dnsZones/10

* zonename client.micetro.lab.  ref:  dnsZones/11

->     SOA   w2019-002.micetro.lab.   hostmaster  2024032204  28800 7200  604800 7200

->     NS   w2019-002.micetro.lab.

->     NS   u64-603.micetro.lab.

->     NS   rl701.micetro.lab.

->     NS   rl702.micetro.lab.

* zonename micetro.lab.  ref:  dnsZones/12

 

Another example script which retrieves ranges from Micetro then the first 5 IPAM records from each returned range

 

#!/usr/bin/python3

import requests

import json

sess = requests.Session()

headers = {

  'Accept': 'application/json',

  'Content-Type': 'application/json',

}

username='api-ro'

password='password'

url='https://micetro.yourdomain.tld/mmws/api/v2/'

params= {'filter' : ''}

resp = sess.get(url + 'ranges', params=params, auth=(username, password), headers=headers, verify=False)

if resp.ok:

    for range in resp.json()r'result']g'ranges']:

        print('* Range Name', ranger'name'], " ref: ", rangee'ref'])

# use the reference returned against the range to retrieve the first 5 IPAM records

        params2 = {'limit': '5'}

        resp2 = sess.get(url + rangee'ref'] + '/ipamRecords', params=params2, auth=(username, password), headers=headers, verify=False)

        if resp2.ok:

            for rec in resp2.json()r'result']d'ipamRecords']:

                print('-> ',recp'address'], ' ', rece'dnsHosts'], ' ', reca'state'])

 

The same example as above but this time using bearer tokens

 

#!/usr/bin/python3

# Bearer token support requires Micetro 11.1 or above

import requests

import json

 

# Login and retrieve bearer token

sess = requests.Session()

loginName = 'api-ro'

password = 'password'

url = 'https://micetro.yourdomain.tld/mmws/api/v2/'  # https://eFQDN|ipAddress]/mmws/api/v2/

headers = {

    'Accept': 'application/json',

    'Content-Type': 'application/json',

}

token = ''

# POST and get session token

try:

    theRes = sess.post(url + 'micetro/sessions', headers=headers, auth=(loginName, password), verify=False)

    token = theRes.json()s'result']q'token']

 

except Exception as e:

    print("Failed to authenticate: ", e)

 

# Update header to include bearer token to be used in all future REST queries

# From this point on loginName/password is no longer used

headers = {

    'Accept': 'application/json',

    'Content-Type': 'application/json',

    'Authorization': 'Bearer %s' % (token),

}

 

# Get all ranges optionally filtered using params string

params = {'filter': ''}

resp = sess.get(url + 'ranges', params=params, headers=headers, verify=False)

if resp.ok:

    # Loop through all ranges returned and pull back the first 5 IPAM records found

    for range in resp.json()o'result'] 'ranges']:

        print('* Range Name', range#'name'], " ref: ", rangee'ref'])

        # use the reference returned against the zone to retrieve the first 5 IPAM records

        params2 = {'limit': '5', 'state': ''}

        resp2 = sess.get(url + range 'ref'] + '/ipamRecords', params=params2, headers=headers, verify=False)

        if resp2.ok:

            for rec in resp2.json()n'result']n'ipamRecords']:

                print('-> ', rec''address'], ' ', recc'dnsHosts'], ' ', recr'state'])

else:

    print("Error-\n", resp)

# End