apiary.apib

FORMAT: 1A
HOST: https://localhost/rest.php/v1

OpenNetAdmin API
================
  The ONA api info

Group Plugins
=============

It is possible to extend ONA with the use of plugins.  Some of these plugins provide their own API endpoints. The following link will show the installed plugins and provide documentation links if available.

# [Plugin documenation index](local/plugins)

<div id="plugcontent" >
</div>
<script>
document.getElementById("plugcontent").innerHTML='<object width="100%" height="100%" type="text/html" data="local/plugins" ></object>';
 var h = document.getElementById("pluginlist").height();
        document.getElementById("plugcontent").height(h);
</script>


Group Authentication
====================

Authentication is handled by the use of a JWT token.
This token must be passed in the `Authorization` header of each transaction.

To obtain a token you must provide a username and password to the `/login` endpoint as described below.

Tokens are subject to an expiration time as well as only being valid when coming from the same client ip that generated it.

To secure your transaction you should configure SSL encryption.

All endpoints can return the `403` HTTP response which indicates an authentication problem. The `status_msg` will contain text describing the specific issue.

# Login [/login{?user,pass}]

## Login [POST]
Use the token field from the resulting json for Authentication.

+ Parameters
    + user: `admin` - The username to authenticate
    + pass: `admin` - The password for authentication

+ Response 200 (application/json;charset=utf-8)

        {"status_code": 0, "status_msg": "Token generation successful", "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJsb2NhbGhvc3QtMTAuMC4yLjE1IiwiYXVkIjoiMTAuMC4ylJiIlcjPYXQiOjE0ODQwNzMwNzMsIm5iZiI6MTQ4NDA3MzA3OCwiZXhwIjoxNDg0MDc2NjczLCJ1c2VybmFtZSI6ImFkbWluIn0.GjABq8Jhi6LY4fDs7ygMVnJVcF1gCdx8PH5uz6pvrqc" }

+ Response 401 (application/json;charset=utf-8)

        {"status_code": 1, "status_msg": "Authentication token not sent" }

+ Response 403 (application/json;charset=utf-8)
  + Attributes (403error)






Group Subnets
=============

Subnets are where ONA stores the IP and network mask for a network. A subnet must exist in the system before and IP addresses can be placed on hosts.

# List multiple subnets [GET /subnets{?name,type,ip,endip,tag,catype,cavalue,fields}]

List all subnets in ONA. Optionally provide search parameters to narrow the returned list.

+ Parameters
  + name: `MY-LAN` (optional) - List subnets matching the string.  Use % as a wildcard character.
  + type: `WAN` (optional) - Existing subnet type defined within ONA.
  + ip: `192.168` (optional) - IP address, any single IP will match the containing subnet. Any missing IPv4 octets will be filled with a 0.
  + endip: `192.168.255.255` (optional) - Must be used in combination with the `ip` option. Provides the end IP in a range of IP addresses to match. Any missing IPv4 octets will be filled with a 255.
  + tag: `mytag,tag2` (optional) - One or more tags to match comma separated.
  + catype: `nmap_scan` (optional) - Subnet with a custom attribute type matching string.
  + cavalue: `Y` (optional) - Subnet with a custom attribute value matching string.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Subnets)

# Create a new subnet [POST /subnets]

Creates a new subnet

+ Request (application/json)
  + Attributes (Subnet Add)

+ Response 201 (application/json;charset=utf-8)
  + Attributes (Subnets)

# Specific Subnet [/subnets/{subnet}{?verbose,fields}]

## List single subnet [GET]
Return information about a single subnet.  Optionally get a verbose output of information.

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.
  + verbose: `Y` (optional) - Display more detailed information about the subnet.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Subnets)

## Modify single subnet [POST]
Modify a subnet and set new values

When setting a `vlan` you must also provide the `campus`.

You can set one or more attributes in your request.

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.

+ Request (application/json)
  + Attributes (Subnet Modify)

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Subnets)

+ Response 400 (application/json;charset=utf-8)

## Delete single subnet [DELETE]
Delete a subnet

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.

+ Response 200 (application/json;charset=utf-8)


## Get next available IP [GET /subnets/{subnet}/nextip/{?offset}]
Request the next available IP address on a subnet

If you use the network name for the `subnet` identifier the starting point
will be the base IP of the subnet. You can provide an `offset` query option to 
start deeper into the subnet.

If you use an IP address on a subnet it will use that IP as the starting
point to search for an available IP.  You can also use `offset` if desired but
it is simpler to just specify a direct IP to start looking for an available.

+ Parameters
  + subnet: `192.168.0.20` - Name or IP of a subnet.
  + offset: `10` (optional) - Offset to add to our subnet input

+ Response 200 (application/json;charset=utf-8)

        {
          "ip_addr": "3232238115",
          "ip_addr_text": "192.168.0.30",
          "status_code": 0,
          "status_msg": ""
        }

# Custom Attributes [/subnets/{subnet}/ca]
## Add Custom Attributes [POST /subnets/{subnet}/ca]
Assign a Custom Attribute to the subnet.

You must provide one of Subnet, Host, or Vlan. This will be done based on the context of the post or the data in the post itself.

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.

+ Request (application/json)
  + Attributes (CA Add)

+ Response 200 (application/json;charset=utf-8)

        {
          "status_code": 0,
          "status_msg": "Custom Attribute nmap_scan (Y) ADDED to: Subnet 192.168.0.0"
        }

## List Multiple Custom Attributes [GET]
List all Custom Attributes assigned to the subnet.

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.

+ Response 200 (application/json;charset=utf-8)

        {
          "custom_attribute_count": 1,
          "custom_attributes": {
            "nmap_scan": "Y"
          },
          "status_code": 0,
          "status_msg": ""
        }



## List Single Custom Attributes [GET /subnets/{subnet}/ca/{type}]
Assign a Custom Attribute to the subnet.

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.
  + type: `nmap_scan` - The type of custom attribute

+ Response 200 (application/json;charset=utf-8)

        { 
          "custom_attribute_count": 1,
          "custom_attributes": {
            "id": "373",
            "table_name_ref": "subnets",
            "table_id_ref": "682",
            "custom_attribute_type_id": "3",
            "value": "Y",
            "name": "nmap_scan",
            "field_validation_rule": "/^[Y|N]$/",
            "failed_rule_text": "Must be either Y or N",
            "notes": "Used to determine if this subnet should be scanned by Nmap based tools."
          },
          "status_code": 0,
          "status_msg": ""
        }

## Modify single Custom Attribute [POST /subnets/{subnet}/ca/{type}]
Modify a custom attribute

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.
  + type: `nmap_scan` - The type of custom attribute.

+ Request (application/json)
  + Attributes (CA Modify)

+ Response 200 (application/json;charset=utf-8)

        {
          "status_code": 0,
          "status_msg": "Updated Custom Attribute type: nmap_scan => 'N'."
        }

+ Response 400 (application/json;charset=utf-8)



## Delete single Custom Attribute [DELETE /subnets/{subnet}/ca/{type}]
Delete a Custom Attribute

+ Parameters
  + subnet: `192.168.0.0` - Name or IP of a subnet.
  + type: `nmap_scan` - The type of custom attribute.

+ Response 200 (application/json;charset=utf-8)


# Data Structures

## `Subnets` (object)
  + include Status
  + subnets (array[Subnet])

## `Subnet` (object)
  + id: `22` (string) - Database unique ID
  + ip_addr: `3232235520` (string) - Numeric representation of an IPv4 or IPv6 address
  + ip_addr_text: `192.168.0.0` (string) - IPv4 or IPv6 address in a dotted notation
  + ip_mask: `4294967040` (string) - Numeric representation of a network mask
  + ip_mask_cidr: `24` (string) - CIDR value for mask
  + ip_mask_text: `255.255.255.0` (string) - Dotted representation of network mask
  + name: `LAN-EXAMPLE` (string) - Name of the subnet
  + subnet_type_id: `13` (string) - Database unique ID for the subnet type
  + subnet_type_name: `LAN` (string) - Name of the subnets type

## `Subnet Add` (object)
  + name: `LAN-EXAMPLE` (string) - Name of the subnet
  + type: `LAN` (string) - Name of the subnets type
  + ip: `192.168.0.0` (string) - IPv4 or IPv6 address in any std format
  + netmask: `255.255.255.0` (string) - IP netmask in dotted or CIDR format
  + vlan: `vlan001` (string, optional) -  Existing vlan name, number to associate this subnet with
  + campus: `CAMPUS` (string, optional) - VLAN campus name or id that `vlan` is assigned to

## `Subnet Modify` (object)
  + set_ip: `192.168.0.0` (string) - IPv4 or IPv6 address in a dotted notation
  + set_netmask: `255.255.255.0` (string) - Dotted or CIDR representation of network mask
  + set_name: `LAN-EXAMPLE` (string) - Name of the subnet
  + set_type: `VLAN` (string) - Subnet type. Must be an existing type in the system
  + campus: `CAMPUS-NAME` (string) - Campus name that `set_vlan` value is assoicated with
  + set_vlan: `VLAN123` (string) - Vlan name to assign, Must provide `campus` as well


Group Domains
=============

A Domain is where ONA stores attributes about a DNS domain. Domains are typically analogus to DNS Zones and are where DNS host names are defined.  A domain must exist in ONA before any hosts can be created. Attributes related to the SOA record are defined here.

# List multiple domains [GET /domains{?fields}]

List all domains in ONA. Optionally provide search parameters to narrow the returned list.

+ Parameters
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Domains)

# Create a new domain [POST /domains]

Creates a new domain

The `sys_config` table stores default values for `dns_domain`. These defaults will be used unless specific new values are provided

+ Request (application/json)
  + Attributes (Domain Add)

+ Response 201 (application/json;charset=utf-8)
  + Attributes (Domains)

# Specific Domain [/domains/{domain}{?fields}]

## List single domain [GET]
Return information about a single domain.

+ Parameters
  + domain: `example.com` - Name of domain.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Domains)

## Modify single domain [POST]
Modify a domain and set new values

You can set one or more attributes in your request.

+ Parameters
  + domain: `example.com` - Name of domain.

+ Request (application/json)
  + Attributes (Domain Modify)

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Domains)

+ Response 400 (application/json;charset=utf-8)

## Delete single domain [DELETE]
Delete a domain

+ Parameters
  + domain: `example.com` - Name or ID of a domain.

+ Response 204 (application/json;charset=utf-8)


# Data Structures

## `Domains` (object)
  + include Status
  + domains (array[Domain])

## `Domain` (object)
  + admin_email: `domains@example.com` (string) - Admin email used for SOA record
  + ctime: `2017-02-02 15:31:47` (string) - Create time
  + default_ttl: `86400` (string) - Default time to live used for SOA record
  + expiry: `1048576` (number) - Domain expire time in seconds, used for SOA record
  + fqdn: `domaintest.com` (string) - Domain fully quailified name
  + id: `60` (string) - Database unique ID
  + minimum: `2560` (number) - Domain expire time in seconds, used for SOA record
  + mtime: `2017-02-02 15:31:47` (string) - Modify time
  + name: `domaintest.com` (string) - Domain name
  + parent_id: `0` (string) - Database unique ID for parent domain record
  + primary_master: `ns1.example.com` (string) - Primary master name server to serve this domain
  + refresh: `16384` (number) - Domain refresh time in seconds, used for SOA record
  + retry: `2048` (number) - Domain retry time in seconds, used for SOA record
  + serial: `22233221` (number) - Domain serial number, system generated, used for SOA record

## `Domain Add` (object)
  + name: `domaintest.com` (string) - Domain name

## `Domain Modify` (object)
  + set_name: `example.com` (string) - New domain name
  + set_admin: `domains@example.com` (string) - Domain admin for SOA record
  + set_primary_master: `server.example.com` (string) - Primary DNS server for NS/SOA record
  + set_refresh: `16384` (number) - Domain refresh time in seconds. Used in SOA record
  + set_retry: `2048` (number) - Domain retry time in seconds. Used in SOA record
  + set_expiry: `1048576` (number) - Domain expiry time in seconds. Used in SOA record
  + set_minimum: `2560` (number) - Domain minimum time in seconds. Used in SOA record
  + set_ttl: `86400` (number) - Domain default TTL time in seconds. Used in SOA record


Group Hosts
=============

A Host is basically a system that runs an OS and has `interfaces` with IP addresses on them.  It has a DNS name to identify the host itself. A host is associated with a `device` that describes the actual hardware make and model. Hosts could be both physical or virtual. A Host can also have a location record associated with it to help identify its physical location.

# List all hosts [GET /hosts{?hostname,domain,mac,ip,endip,location,notes,model,role,manufacturer,tag,catype,cavalue,fields}]

List all hosts in ONA. Optionally provide search parameters to narrow the returned list.

+ Parameters
  + hostname: `host` (optional) - List hosts with the host portion matching this string. Can be used with domain to form an FQDN.
  + domain: `example.com` (optional) - Match hosts in the domain. Can be used with hostname to form an FQDN. % wildcards are not supported here.
  + mac: `005056A7FFFA` (optional) - Match a specific MAC address, should be only 0-9 and A-F formated.
  + ip: `192.168` (optional) - IP address, any single IP will match the containing subnet. Any missing IPv4 octets will be filled with a 0.
  + endip: `192.168.255.255` (optional) - Must be used in combination with the `ip` option. Provides the end IP in a range of IP addresses to match. Any missing IPv4 octets will be filled with a 255.
  + location: `LAX` (optional) - Match based on location. Can be short or long name for location, also postal code.
  + notes: `Some text string` (optional) - Match based on notes field. Use % as a wildcard character.
  + model: `3750` (optional) - Match on the device model identifier.
  + role: `Switch` (optional) - Match on the device role.
  + manufacturer: `Cisco` (optional) - Match on the device manufacturer.
  + tag: `mytag,tag2` (optional) - One or more tags to match, comma separated.
  + catype: `nmap_scan` (optional) - Subnet with a custom attribute type matching string.
  + cavalue: `Y` (optional) - Subnet with a custom attribute value matching string.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Hosts)

# Create a new host [POST /hosts]
Creates a new host

+ Request (application/json)
  + Attributes (Host Add)

+ Response 201 (application/json;charset=utf-8)
  + Attributes (Hosts)

# Specific Host [/host/{host}{?fields}]

## List single host [GET]
Return information about a single host.

The host value can be an ID, FQDN, IP, MAC. Any of these items can be used as the lookup to identify a single host. It must be a unique value. It is recomended to use the Primary FQDN of the host.

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Hosts)

## Modify single host [POST]
Modify a host and set new values

You can set one or more attributes in your request.

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.

+ Request (application/json)
  + Attributes (Host Modify)

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Hosts)

+ Response 400 (application/json;charset=utf-8)

## Delete single host [DELETE]
Delete a host

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.

+ Response 200 (application/json;charset=utf-8)


# Custom Attributes [/hosts/{host}/ca]
## Add Custom Attributes [POST /hosts/{host}/ca]
Assign a Custom Attribute to the host.

You must provide one of Subnet, Host, or Vlan. This will be done based on the context of the post or the data in the post itself.

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.

+ Request (application/json)
  + Attributes (CA Add)

+ Response 200 (application/json;charset=utf-8)

        {
          "status_code": 0,
          "status_msg": "Custom Attribute nmap_scan (Y) ADDED to: Subnet 192.168.0.0"
        }

## List Multiple Custom Attributes [GET]
List all Custom Attributes assigned to the host.

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.

+ Response 200 (application/json;charset=utf-8)

        {
          "custom_attribute_count": 1,
          "custom_attributes": {
            "nmap_scan": "Y"
          },
          "status_code": 0,
          "status_msg": ""
        }



## List Single Custom Attributes [GET /hosts/{host}/ca/{type}]
Assign a Custom Attribute to the host.

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.
  + type: `nmap_scan` - The type of custom attribute

+ Response 200 (application/json;charset=utf-8)

        { 
          "custom_attribute_count": 1,
          "custom_attributes": {
            "id": "373",
            "table_name_ref": "hosts",
            "table_id_ref": "682",
            "custom_attribute_type_id": "3",
            "value": "Y",
            "name": "nmap_scan",
            "field_validation_rule": "/^[Y|N]$/",
            "failed_rule_text": "Must be either Y or N",
            "notes": "Used to determine if this subnet should be scanned by Nmap based tools."
          },
          "status_code": 0,
          "status_msg": ""
        }

## Modify single Custom Attribute [POST /hosts/{host}/ca/{type}]
Modify a custom attribute

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.
  + type: `nmap_scan` - The type of custom attribute.

+ Request (application/json)
  + Attributes (CA Modify)

+ Response 200 (application/json;charset=utf-8)

        {
          "status_code": 0,
          "status_msg": "Updated Custom Attribute type: nmap_scan => 'N'."
        }

+ Response 400 (application/json;charset=utf-8)



## Delete single Custom Attribute [DELETE /hosts/{host}/ca/{type}]
Delete a Custom Attribute

+ Parameters
  + host: `router.example.com` - Fully Qualified Domain Name (FQDN) or IP to identify host.
  + type: `nmap_scan` - The type of custom attribute.

+ Response 200 (application/json;charset=utf-8)


# Data Structures

## `Hosts` (object)
  + include Status
  + hosts (array[Host])

## `Host` (object)
  + description: `Internet Link` (optional,string) - Descritption of the host.
  + host_id: `925` (string) - ID of host the host belongs to.
  + id: `2185` (string) - ID of the host itself.
  + ip_addr: `336294712248048576396240581215362482189` (string) - Numeric representation of the IP address.
  + ip_addr_text: `fd00:172:25:1::d` (string) - Textual representation of the IP address.
  + last_response: `null` (string) - Timestamp of last ICMP responce. Updated when nmap_scan plugin is used.
  + mac_addr: `005056A7009A` (string) - Layer 2 MAC address for host.
  + name: `FastEthernet1/0` (string) - Host name as used by the OS.
  + nat_host_id: `0` (string) - ID reference to the host that represents the NAT address.
 
## `Host Add` (object)
  + description: `Internet Link` (string) - Descritption of the host.
  + host: `host.example.com` (string) - Hostname or ID new host is associated with.
  + ip: `fd00:172:25:1::d` (string) - Textual representation of the IP address.
  + mac: `005056A7009A` (string) - Layer 2 MAC address for host. Any typical format is supported.
  + type: `Unknown, Unknown (Manually Added)` (string) - Select the device type. Consists of a Manufacturer, Model (Role).
  + name: `FastEthernet1/0` (string) - Host name as used by the OS.
  + natip: `20.20.15.75` (string) - IP of NAT address to add with this new host.
  + addptr: `Y` (string) - Auto add a PTR record for new IP pointing to host value.
  + force: `Y` (string) - Force duplicate MAC address. Generally Macs are globally unique, allow duplicate macs on different subnets.

## `Host Modify` (object)
  + set_description: `Internet Link` (string) - Descritption of the host.
  + host: `host.example.com` (string) - Hostname or ID new host is associated with.
  + host: `10.1.1.1` (string) - IP or ID of specific host to modify.
  + set_ip: `fd00:172:25:1::d` (string) - Textual representation of the IP address.
  + set_mac: `005056A7009A` (string) - Layer 2 MAC address for host. Any typical format is supported.
  + set_name: `FastEthernet1/0` (string) - Host name as used by the OS.
  + set_last_response: `2012-06-27 12:02:50` (string) - Timestamp IP was last seen.
  + use_primary: `Y` (string) - Modify the host's primary host (only applies when "host" option is used and multiple IPs exist!).






Group Interfaces
=============

An Interface is where IP addresses are allocated. They also contain attributes about the physical interface name and MAC address. All `hosts` must have at least one interface allocated to them. You can allocate as many more interfaces as desired to a single host. Interfaces can also be shared with one other host for the HSRP,VRRP,CARP type use case.

# List all interfaces [GET /interfaces{?host,ip,endip,mac,fields}]

List all interfaces in ONA. Optionally provide search parameters to narrow the returned list.

+ Parameters
  + host: `host.example.com` (optional) - Match hostname matching this string.
  + ip: `192.168` (optional) - IP address, any single IP will match the containing subnet. Any missing IPv4 octets will be filled with a 0.
  + endip: `192.168.255.255` (optional) - Must be used in combination with the `ip` option. Provides the end IP in a range of IP addresses to match. Any missing IPv4 octets will be filled with a 255.
  + mac: `005056A7FFFA` (optional) - Match a specific MAC address, should be only 0-9 and A-F formated.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Interfaces)

# Create a new interface [POST /interfaces]
Creates a new interface associated with an existing `host` record

+ Request (application/json)
  + Attributes (Interface Add)

+ Response 201 (application/json;charset=utf-8)
  + Attributes (Interfaces)

# Specific Interface [/interface/{ip}{?fields}]

## List single interface [GET]
Return information about a single interface.

+ Parameters
  + ip: `192.168.0.20` - IP address. IPv4 and IPv6 formats are supported.
  + fields: `id,name` (optional) - A comma separated list of specific result fields to return.

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Interfaces)

## Modify single interface [POST]
Modify a interface and set new values

You can set one or more attributes in your request.

+ Parameters
  + ip: `192.168.0.20` - IP address. IPv4 and IPv6 formats are supported.

+ Request (application/json)
  + Attributes (Interface Modify)

+ Response 200 (application/json;charset=utf-8)
  + Attributes (Interfaces)

+ Response 400 (application/json;charset=utf-8)

## Delete single interface [DELETE]
Delete a interface

+ Parameters
  + ip: `192.168.0.20` - IP address. IPv4 and IPv6 formats are supported.

+ Response 200 (application/json;charset=utf-8)


# Data Structures

## `Interfaces` (object)
  + include Status
  + interfaces (array[Interface])

## `Interface` (object)
  + description: `Internet Link` (optional,string) - Descritption of the interface.
  + host_id: `925` (string) - ID of host the interface belongs to.
  + id: `2185` (string) - ID of the interface itself.
  + ip_addr: `336294712248048576396240581215362482189` (string) - Numeric representation of the IP address.
  + ip_addr_text: `fd00:172:25:1::d` (string) - Textual representation of the IP address.
  + last_response: `null` (string) - Timestamp of last ICMP responce. Updated when nmap_scan plugin is used.
  + mac_addr: `005056A7009A` (string) - Layer 2 MAC address for interface.
  + name: `FastEthernet1/0` (string) - Interface name as used by the OS.
  + nat_interface_id: `0` (string) - ID reference to the interface that represents the NAT address.
 
## `Interface Add` (object)
  + description: `Internet Link` (string) - Descritption of the interface.
  + host: `host.example.com` (string) - Hostname or ID new interface is associated with.
  + ip: `fd00:172:25:1::d` (string) - Textual representation of the IP address.
  + mac: `005056A7009A` (string) - Layer 2 MAC address for interface. Any typical format is supported.
  + name: `FastEthernet1/0` (string) - Interface name as used by the OS.
  + natip: `20.20.15.75` (string) - IP of NAT address to add with this new interface.
  + addptr: `Y` (string) - Auto add a PTR record for new IP pointing to host value.
  + force: `Y` (string) - Force duplicate MAC address. Generally Macs are globally unique, allow duplicate macs on different subnets.

## `Interface Modify` (object)
  + set_description: `Internet Link` (string) - Descritption of the interface.
  + host: `host.example.com` (string) - Hostname or ID new interface is associated with.
  + interface: `10.1.1.1` (string) - IP or ID of specific interface to modify.
  + set_ip: `fd00:172:25:1::d` (string) - Textual representation of the IP address.
  + set_mac: `005056A7009A` (string) - Layer 2 MAC address for interface. Any typical format is supported.
  + set_name: `FastEthernet1/0` (string) - Interface name as used by the OS.
  + set_last_response: `2012-06-27 12:02:50` (string) - Timestamp IP was last seen.
  + use_primary: `Y` (string) - Modify the host's primary interface (only applies when "host" option is used and multiple IPs exist!).




Group Custom Attributes
=======================


## Add Custom Attributes [POST /ca]
Assign a Custom Attribute to the ojbect.

You must provide one of Subnet, Host, or Vlan.

+ Request (application/json)
  + Attributes (CA Add Direct)

+ Response 200 (application/json;charset=utf-8)

        {
          "status_code": 0,
          "status_msg": "Custom Attribute nmap_scan (Y) ADDED to: Subnet 192.168.0.0"
        }

## List Multiple Custom Attributes [GET /ca{?fields}]
List all Custom Attributes assigned to the object.

You must provide one of Subnet, Host, or Vlan.

+ Request (application/json)
  + Attributes (CA)

+ Response 200 (application/json;charset=utf-8)

        {
          "custom_attribute_count": 1,
          "custom_attributes": {
            "nmap_scan": "Y"
          },
          "status_code": 0,
          "status_msg": ""
        }


# Specific Custom Attributes [/ca/{type}]
## List Single Custom Attributes [GET]
Assign a Custom Attribute.

You must provide one of Subnet, Host, or Vlan.

+ Parameters
  + type: `nmap_scan` - The type of custom attribute

+ Request (application/json)
  + Attributes (CA)

+ Response 200 (application/json;charset=utf-8)

        { 
          "custom_attribute_count": 1,
          "custom_attributes": {
            "id": "373",
            "table_name_ref": "subnets",
            "table_id_ref": "682",
            "custom_attribute_type_id": "3",
            "value": "Y",
            "name": "nmap_scan",
            "field_validation_rule": "/^[Y|N]$/",
            "failed_rule_text": "Must be either Y or N",
            "notes": "Used to determine if this subnet should be scanned by Nmap based tools."
          },
          "status_code": 0,
          "status_msg": ""
        }

## Modify single Custom Attribute [POST]
Modify a custom attribute

You must provide one of Subnet, Host, or Vlan.
+ Parameters
  + type: `nmap_scan` - The type of custom attribute.

+ Request (application/json)
  + Attributes (CA Modify Direct)

+ Response 200 (application/json;charset=utf-8)

        {
          "status_code": 0,
          "status_msg": "Updated Custom Attribute type: nmap_scan => 'N'."
        }

+ Response 400 (application/json;charset=utf-8)



## Delete single Custom Attribute [DELETE]
Delete a Custom Attribute

You must provide one of Subnet, Host, or Vlan.

+ Parameters
  + type: `nmap_scan` - The type of custom attribute.

+ Request (application/json)
  + Attributes (CA)

+ Response 200 (application/json;charset=utf-8)




Data Structures
===============

## `403error` (object)
  + status_code: `1` - Non zero error code
  + status_msg: `Token Issue: some sort of error` - Message about Token issue, should contain text describing specific issue

## `Status` (object)
  + status_code: `0` (number) - Status code from module
  + status_msg: `Successfully did the thing you asked` (string) - A human readable status message

## `CA` (object)
  + subnet: `192.168.0.0` (string) - Use if Custom Attribute is assoicated with a Subnet
  + host: `host.example.com` (string) - Use if Custom Attribute is assoicated with a Host
  + vlan: `VLAN-EXAMPLE` (string) - Use if Custom Attribute is assoicated with a Vla

## `CA Add` (object)
  + type: `nmap_scan` (string) - The type of Custom Attribute
  + value: `Y` (string) - The value of the Custom Attribute

## `CA Modify` (object)
  + set_value: `N` (string) - New value for the Custom Attribute

## `CA Add Direct` (object)
  + include CA
  + include `CA Add`

## `CA Modify Direct` (object)
  + include CA
  + include `CA Modify`