0.0
No commit activity in last 3 years
No release in over 3 years
A client gem for Men & Mice IPAM via JSON-RPC
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 2.0
~> 1.6
~> 11.0
>= 0
>= 0
>= 0
 Project Readme

Build Status

MmJsonClient

The MmJsonClient gem is used to access the Men and Mice IPAM API using the JSON-RPC format that was first made available in version 6.6.

API Versions

In order to minimize run time dependencies this gem includes API definition files that define the enumerations, methods and types available when using the gem.

Different versions of this gem support different versions of the API by default. See API Definitions for more information.

Gem Version Default API Version
0.x 7.x
2.x 9.x

Usage

Basic Connection Setup

require 'mm_json_client'
client = MmJsonClient::Client.new(server: 'my-ipam.example.com',
                                  username: 'demo',
                                  password: 'demo')
client.login

Optional parameters to Client.new are:

Parameter Values Purpose
endpoint: string The URI for the web service. Defaults to /_mmwebext/mmwebext.dll?Soap.
open_timeout: integer Seconds to wait for the initial connection to time out. Defaults to 10.
port: integer The TCP port for the connection. Defaults to 80 or 443 if SSL is enabled.
proxy: string The M&M API server. Defaults to the same as the server: parameter.
ssl: true/false Use SSL for the connection. Defaults to false.
verify_ssl: true/false Whether to validate SSL certificates. Defaults to true.

Advanced Connection Setup

The client can optionally take an array of servers for the proxy: parameter. This allows you to have redundant API servers without a load balancer.

This also allows you to handle the case where the web server is running on the same servers as the Central service in a cluster configuration. This is important, because in this architecture the web component connects to the local server instead of using the DNS round robin entry and if you pick the inactive server then you will receive an error about operations being disabled.

# When you have multiple web servers that are not behind a load balancer.
client = MmJsonClient::Client.new(proxy: ['my-ipam01.example.com',
                                          'my-ipam02.example.com'],
                                  server: 'ipam-cluster-name.example.com',
                                  username: 'demo',
                                  password: 'demo')

# When you have the web role on the M&M central servers in a cluster and need
# to make sure you can connect to a functioning one.
client = MmJsonClient::Client.new(proxy: ['my-ipam01.example.com',
                                          'my-ipam02.example.com'],
                                  server: 'localhost',
                                  username: 'demo',
                                  password: 'demo')

Case Conversion

Methods, parameters, and values returned from the API use snake case instead of camel case as listed in the M&M API docs. Class and enumeration names still use Pascal case.

Making Requests

The methods in the M&M API will be available directly on the client. Any required or optional parameters can be included as a hash. The client will return a response object that matches what is in the API docs.

Retrieving Data

# Get all of the DNS zones
response = client.get_dns_zones
puts "Found #{response.total_results} zones on the server."
puts "The first one is #{response.dns_zones.first.name}."

# Search for a particular zone
response = client.get_dns_zones(filter: 'name:^demo.example.com.$')
puts "Found #{response.total_results} zones on the server."
puts "The first one is #{response.dns_zones.first.name}."

# Get all sub-zones from a particular zone.
response = client.get_dns_zones(filter: 'name:example.com.$')
puts "Found #{response.total_results} zones on the server."
puts "The first one is #{response.dns_zones.first.name}."

# Get a single dns zone by reference.
response = client.get_dns_zone(dns_zone_ref: '{#4-#1000}')
zone = response.dns_zone
puts "The zone name is #{zone.name}."

Making Changes

When you need to create a type to use as a parameter to a method you will instantiate it, modify it as necessary and then pass it in.

new_user = MmJsonClient::User.new
new_user.name = 'demouser'
new_user.password = 'password'
new_user.authentication_type = 'Internal'

# or

new_user = MmJsonClient::User.new(name: 'demouser',
                                  password: 'password',
                                  authentication_type: 'Internal')

# and then
client.add_user(user: new_user)

Enumerated Values

Some fields in the API such as AuthenticationType are enumerated values. To see valid values for the enumation use the .values method.

MmJsonClient::Enums::AuthenticationType.values
=> ["Internal", "AD", "ADGroup", "RADIUS"]

Learning and Exploration

There are some examples in this repository.

Check out the SOAP API docs on your server. Although this gem is using the JSON-RPC API, the methods, types, enumerations and responses are the same.

If you have completion enabled in your IRB session you will be able to complete on method, type, and enumeration names.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ewannema/mm_json_client.

License

The gem is available as open source under the terms of the MIT License.