Infoblox WAPI documentation

Introduction

The Infoblox WAPI is an interface based on REST (REpresentational State Transfer), also called a RESTful web API. It uses HTTP methods for operations and supports input and output in JSON and XML.

Notation

The following conventions are used to describe syntax for WAPI methods and objects:

What

Description

objref

A reference to an object. This must be a reference returned from an earlier call. For more information, see Object Reference.

WAPI

Used as a generic start in an URL. In real calls, this needs to be replaced with /wapi/v2.13.6 or similar syntax.

objtype

The name of an object type, such as network.

field

The name of a field, such as comment.

value

The value of an item, such as a field. The value must be quoted according to where it is used. For information, see Naming and Values.

[thing]

These brackets are used to signify an optional value.

a | b

The symbol | is used to indicate that either a or b can be used.

thing…

... is used at the end of an item to signify that it can be repeated multiple times. Items must be separated in accordance with where they are used, such as & in arguments.

{ }

These brackets are used to group information in descriptions.

Transport and Authentication

WAPI uses HTTPS (HTTP over SSL/TLS) as the transport mechanism. The server certificate used for WAPI is the same certificate used by NIOS for the GUI and PAPI.

WAPI supports both HTTP basic authentication and certificate-based authentication. For certificate-based authentication, see URL here. It is supported to use the connection for multiple requests. In this case, authentication is handled by supplying the cookie (ibapauth) that was returned after the initial authentication. This cookie can be invalidated by sending a POST request to /wapi/v2.13.6/logout

WAPI supports the same underlying authentication methods that NIOS supports for username and password. All WAPI users must have permissions that grant them access to the API (same as PAPI).

Backward Compatibility

The Infoblox WAPI has a versioning scheme that is independent of the NIOS versioning scheme. The current WAPI version is 2.13.6.

A current WAPI version is backward compatible with WAPI releases that have the same major WAPI version or with designated earlier major versions. Though the protocol itself may not be strictly backward compatible, the server emulates the correct behavior, when necessary.

For example, a client that uses WAPI version X behaves the same way in version Y if X is supported by Y (that is X is lower than Y and X has the same major version as Y or X uses a major version that is supported by Y).

The WAPI protocol is versioned (see URL in General Syntax and Options) independently from NIOS. Refer to the release notes for information about the WAPI version.

Requirements and exceptions:

  • Rely on errors returned by HTTP Error Status only, not by text messages or other components.

  • New objects and fields may exist in a later WAPI version. Thus, additional fields may be returned and must be ignored.

  • New syntaxes and values may be supported. Do not rely on receiving errors for illegal usage.

  • In the URL, use the WAPI version that corresponds to the behavior you expect. Do not combine requests using different WAPI versions in the same session or connection.

General Syntax and Options

All WAPI requests consist of three parts; URL, Arguments and Data (body).

URL

The first part of the URL identifies the requests as a WAPI request and specifies the expected version of WAPI. The URL syntax is wapi/v major.minor, e.g. wapi/v3.4/. The current version of the API is 2.13.6.

The second part of the URL identifies the resource, such as a network, on which the request operates.

Arguments

CGI query arguments (after ?) can be used to specify general options and method specific options and data for the request. All options start with the character _ (underscore).

The general options are:

Option

Description

_return_type

Data format for returned values; defaults to json. Valid choices: json, json-pretty, xml, xml-pretty. -pretty variants are the same except that they are formatted for readability. For more information, see Data Formats.

_method

An alternative way of specifying HTTP method and overrides the method used. The default is to use the actual HTTP method. Valid choices: GET, PUT, DELETE and POST

Argument key = value pairs must be separated with &. The values must be quoted using % xx notation if they contain the following: =, &, +, %, or space.

You can specify only atomic values as arguments (i.e. booleans, integers, or strings). You must use a method that contains a body if lists or structures are needed. Example: POST with _method=GET can be used for searching.

In all method descriptions, you can use general options with all requests unless specifically noted.

The methods have additional options as described in their respective sections.

The following table lists the scheduling and approval specific options. Note that you can apply these options only to PUT, POST and DELETE requests.

Option

Description

_schedinfo.scheduled_time

If set, the requested operation will be scheduled for later execution at the specified time (specified in Epoch seconds). A reference to the created scheduledtask object will be returned. Only one of scheduled_time and schedule_now can be set in the request.

_schedinfo.schedule_now

If set to True, the operation will be scheduled for execution at the current time. Note that only scheduled_time or schedule_now can be set in the request.

_schedinfo.predecessor_task

Optional reference to a scheduled task that will be executed before the submitted task.

_schedinfo.warnlevel

Optional warning level for the operation, valid values are ‘WARN’ and ‘NONE’. If not specified, ‘NONE’ will be used.

_approvalinfo.comment

Comment for the approval operation (this can be optional or required depending on the settings for the approval workflow).

_approvalinfo.query_mode

Optional query mode for the approval operation. Valid values are “true” or “false”, if this is set to true and the request would have required approval, an error message will be returned. The default value for this is “false”.

_approvalinfo.ticket_number

Ticket number for the approval operation (this can be optional or required depending on the settings for the approval workflow).

Data (Body)

Contains data that is dependent on the method. For information about data format and how to specify it, see Data Formats. Only, PUT, and POST methods can have a Body on input. All methods have Body on output.

Example

The GET request:

https://1.2.3.4/wapi/v2.13.6/networkview?
_return_type=xml-pretty&name=default

Returns with a body:

<?xml version="1.0"?>
<list>
  <value type="object">
    <is_default type="boolean">true</is_default>
    <_ref>networkview/ZG5zLm5ldHdvcmtfdmlldyQw:default/true</_ref>
    <name>default</name>
  </value>
</list>

Naming and Values

WAPI uses a leading underscore (_) for all reserved arguments, fields, and items. Example: _return_type and _ref.

Fields in objects always start with a letter (a-z) and are followed by a zero or more letters, digits, and underscores. No other characters are used in field identifiers.

Field and argument values must be quoted according to where they are used. Examples:

URL/CGI args, x-www-form-urlencoded:

Use %xx encoding for “%”, “;”, “/”, “?”, “:”, “@”, “&”, “=”, “+”, “$”, “,” and ” ” (a space)

JSON Data:

Use JSON quoting, as specified at http://json.org

XML Data

Use XML quoting (&amp; etc.) as needed for XML.

Values set in WAPI object fields might differ from the effective value used for that particular field during product operation, which could be a value inherited from the Grid or the Grid Member depending on the particular object in question and the state of the object use flags.

Object Reference

WAPI Objects are referenced using their Object References. WAPI returns this reference when an object is created, modified, deleted or read. This reference is used to identify the object for the same operations.

An object reference is a string with the following format, without spaces:

wapitype / refdata [ : name1 [ { / nameN }… ] ]

Component

Description

wapitype

The object type being referenced. Example: network.

refdata

Opaque internal object identifier. A sequence of letters, digits, “-” (dash) and “_” (underscore).

nameN

Object type dependent name component N. The component describes the object being referenced. This is only returned for objects with a defined name format. It is always optional on input and never used by the server.

The documentation for each object type describes the format of its name components. Name components are separated by “/” (or only one component without a “/”). Each name component uses the URL quoting method (%xx notation) when necessary (for example if it contains a “/” character).

If the name is defined for the object type, it can be used by a client to get basic information about an object without retrieving the full object. Example: the name of a host. However, an object’s name is not guaranteed to uniquely identify an object unless specifically noted in its description.

The name is not used by the WAPI server on input, and any supplied value is disregarded. For example, a client is free to send a previously returned reference to the server, with or without the name part, including the leading colon (:). The result is not affected.

Note that non-ascii values in name are returned using % notation, and should be interpreted as hex-encoded utf-8.

Example:

record:cname/ZG5 .... DE:t1.webapi16.foo.bar/default

Function Calls

Functions are associated with particular objects. The method specific option _function should be used to specify the name of function to call. Only POST method allows function calls. You can use either CGI argument key = value pairs or request’s data(body) to specify values for function arguments. Simultaneous use of CGI arguments and data(body) is not supported.

Example 1

The POST request:

https://1.2.3.4/wapi/v2.13.6/network/
ZG5zLm5ldHdvcmskMTAuMC4wLjAvMjQvMA:10.0.0.0/24/default?
_function=next_available_ip&num=3

Returns with a body:

{
    "ips": [
        "10.0.0.1",
        "10.0.0.2",
        "10.0.0.3"
    ]
}

Example 2

The POST request:

https://1.2.3.4/wapi/v2.13.6/network/
ZG5zLm5ldHdvcmskMTAuMC4wLjAvMjQvMA:10.0.0.0/24/default?
_function=next_available_ip

Sent with a body:

{
    "num": 3
}

Returns with a body:

{
    "ips": [
        "10.0.0.1",
        "10.0.0.2",
        "10.0.0.3"
    ]
}

Extensible Attributes

Object types that allow for extensible attributes have a field called extattrs, which can be read by including the name in the _return_fields option of the GET method.

Extensible attributes are sets of name value pairs in which the values can be lists, if the attribute allows for multiple values.

Searching for extensible attributes requires the use of a special syntax, as described under the GET method.

Use Flags

Some fields are associated with a corresponding boolean flag value that has the prefix use_. For example, ttl is associated with the flag use_ttl. In an object, the value of this field will only take effect when its use flag is true. Otherwise, the value will be inherited from a higher level setting.

Use flags and fields that contain the flags behave mostly like other object fields. They are special in the following ways:

  • All use flags have names such as “use_*”, where “*” is typically the name of the associated field. Multiple fields may share the same use flag.

  • Use flags can be read using _return_fields.

  • If a field is part of the default fields returned on read (“basic object”), its associated use flag (if any) will also be included in the default set.

  • Use flags can be written by PUT or POST requests.

  • Writing a field that has a corresponding use flag will automatically set the use flag to true, unless the same request also sets the use flag to false.

Data Formats

Input

The body of the HTTP request contains data for the PUT and POST requests only. The format of the data defaults to JSON, but it can be changed using Content-Type: header. The valid content types are:

Content Type

Description

application/json

JSON format, see http://json.org for more information.

application/xml

XML format, see XML Format for more information.

text/xml

Alternative way to specify application/xml.

application/x-www-form-urlencoded

Arguments to method encoded in body. This is the same as specification after ?, but it can handle longer sequences and is directly supported by HTML forms. If arguments are encoded in the body, CGI query arguments won’t be allowed.

Output

Data returned to the client defaults to JSON, but can be changed using either Accept: header or _return_type. Accept: takes the same values as Content-Type, listed above (for exceptions to this, see Error Handling); _return_type overrides any Accept: header.

XML Format

WAPI uses the following XML constructs:

Element

Description

<list>

Array, child nodes are items in list. Names of child elements are not significant (and can be same).

<X type=”object”>

Object X, child nodes are members of object. X can be any value if used outside an object context

<X type=”T”>

Field X of object. Its value is the text of the element. Allowed types (T) are int, float, boolean and string (as in XML Schema Definition). String is the default and is not explicitly specified using type= on output.

<X null=”true”/>

Field X with value null/None.

Field syntax is used for “bare” values in list/array or as single values. X is not significant and will always be value on output.

No name spaces are used or specified.

Example: XML (xml-pretty style):

<?xml version="1.0"?>
<list>
  <value type="object">
    <comment null="true"/>
    <_ref>network/ZG5zLm5ldHdvcmskMTAuMC4wLjAvOC8w:20.0.0.0/8/default</_ref>
    <disable type="boolean">false</disable>
    <network>20.0.0.0/8</network>
    <network_view>default</network_view>
  </value>
</list>

If X is considered an illegal XML tag name, or if it begins with “tag” and is followed by a number it will be renamed to tag0-N and an additional “name” property will be added on retrieval and expected on input. For example, the XML for an object with extensible attributes that contain spaces in their names would look like the following:

<?xml version="1.0"?>
<list>
  <value type="object">
    <network>8.0.0.0/8</network>
    <extattrs type="object">
      <tag0 name="12345" type="object">
        <value>d</value>
      </tag0>
      <tag1 name="tag0" type="object">
        <value>c</value>
      </tag1>
      <tag2 name="this is a test" type="object">
        <value>b</value>
      </tag2>
    </extattrs>
    <_ref>network/ZG5zLm5ldHdvcmskOC4wLjAuMC84LzA:8.0.0.0/8/default</_ref>
  </value>
</list>

Error Handling

All errors return a HTTP status code of 400 or higher.

All methods use the following generic error status codes. Specific return codes used for a method are specified for each method.

Status

Description

400

Bad Request. The request from the client is incorrect. This could be syntax errors in the request or data conflict issues on the server side. The request should not be repeated as is unless the error condition has been cleared (i.e. either the request syntax corrected or the state of the database changed.)

500

Server Error. The error was not caused by any error in the request. Depending on the error the request may be successfully repeated as is. If not possible to resolve, please report to Infoblox (including the full error return with the “trace”).

4xx codes refer to errors caused by the request or the data. To some extent, all of these are user errors.

5xx codes refer to server or internal errors. These errors point to deficiency in the server code and are not usually possible under normal conditions.

When the server returns an error with status code >= 400, the body is always in JSON format, irrespective of any Accept or _return_types.

The returned message conforms to JSON, but is formatted to ensure that the first line of the body always contains the text “Error,” an error type, and an error message.

A client that only gives a description of the error can simply show the first returned line.

The full returned error data is an object with the following fields (all values are strings):

Field

Value

Error

Error type (followed by an explanation after :).

code

Symbolic error code.

text

Explanation of the error.

trace

Debug trace from the server, only if debug is on.

Example of Error Return (trace shortened):

{ "Error": "AdmConProtoError: Unknown argument/field: netwdork",
  "code": "Client.Ibap.Proto",
  "text": "Unknown argument/field: netwdork",
  "trace": "  File "/infoblox/common/lib/python/info..."
}

Methods

GET

Search and Read Objects: GET Method

HTTP GET is used to read a single object or to search for objects.

Syntax

GET WAPI / objref [ ? option… ]

or

GET WAPI / objtype [ ? { option | condition }… ]

Description

GET is used to read objects. The objects to read can be specified either by using an Object Reference (objref) to read one specific object or by searching for objects of a specific type (objtype) with the given search conditions.

Arguments to the search (objtype) form are field names and values to match. If no arguments are used, all object for the object type objtype are returned.

The number of objects returned is limited by the option _max_results or, if _max_results is not specified, 1000 objects. If _max_results is not specified, the appliance returns an error when the number of returned objects would exceed 1000. Similarly, if _max_results is set to -500 (maximum of 500 objecs) the appliance returns an error if the number of returned objects would exceed 500.

Options

Method Option

Description

_max_results

Maximum number of objects to be returned. If set to a negative number the appliance will return an error when the number of returned objects would exceed the setting. The default is -1000. If this is set to a positive number, the results will be truncated when necessary.

_return_fields

List of returned fields separated by commas. The use of _return_fields repeatedly is the same as listing several fields with commas. The default is the basic fields of the object.

_return_fields+

Specified list of fields (comma separated) will be returned in addition to the basic fields of the object (documented for each object).

_return_as_object

If set to 1, a results object will be returned (see below for more information). If not specified, it defaults to 0.

_paging

If set to 1, the request is considered a paging request (see below for more information). If not specified, it defaults to 0. If set, _max_results must also be set.

_page_id

If set, the specified page of results will be returned.

_proxy_search

If set to ‘GM’, the request is redirected to Grid master for processing. If set to ‘LOCAL’, the request is processed locally. This option is applicable only on vConnector grid members. The default is ‘LOCAL’.

_schema

If this option is specified, a WAPI schema will be returned (see below for more information).

_schema_version

If this option is specified, a WAPI schema of particular version will be returned. If options is omitted, schema version is assumed to be 1. For the full list of available versions please refer to information below.

_get_doc

If this option is specified, a WAPI schema with documentation will be returned. Applicable only when _schema_version is 2.

_schema_searchable

If this option is specified, search only fields will also be returned. Applicable only when _schema_version is 2.

_inheritance

If this option is set to True, fields which support inheritance, will display data properly.

Arguments

There can be no arguments to objtype or it can have one or multiple conditions in the following format:

{ field | * attribute [ <space> ] } [ modifiers ] = value

Where:

field is a documented field of the object.

attribute is the name of an extensible attribute. Must be prefixed by an asterisk (*) and optionally followed by a single space.

modifiers is optional and can be one or more search modifiers supported by the field or extensible attribute value type.

value is the value or regular expression to search for.

When combining multiple conditions, all must be satisified in order to match an object (i.e. conditions are combined with AND).

When a field is a list or an extensible attribute that can have multiple values, the condition is true if any value in the list matches.

If no modifiers are used, it is an exact match.

Search Modifiers

A search argument can use the following modifiers:

Modifier

Functionality

!

Negates the condition.

:

Makes string matching case insensitive.

~

Regular expression search. Expressions are unanchored.

<

Less than or equal.

>

Greater than or equal.

Only one of the following can be specified at one time: greater than, less than, and regular expressions.

You can find the modifiers that are supported by each field in the respective documentation. Unsupported combinations will result in an error.

Depending on the attribute type, following are modifiers supported by extensible attributes:

integer and date support !, < and >. All other types behave like strings and support !, ~ and :.

Data Returned

In the object reference form (objref) only one object is returned (as an object, not a list). In the search form (objtype) the request always returns a list of objects (even if zero or one objects is returned).

Objects returned will by default consist of a set of basic fields, as listed in the documentation. The option _return_fields can be used to request a specific set of fields to return.

Fields that have no value (not set in the NIOS database) or that are not allowed to be accessed by the user because of group access rights will not be returned (i.e. silently left out of the result).

Returned objects will also contain a _ref field, containing the reference of the object. This can be used in subsequent calls that require a reference.

If a search matches no objects, an empty list will be returned.

If a results object is requested, an object with the following fields will be returned:

Field

Present

Description

result

Always

Actual result of the read operation, this is a list of objects.

next_page_id

Optional

If there was a paging request, this is the ID for the next page of results.

Some fields refer to other subobjects. Some of these fields also support nested return fields (see the field’s ‘Type’ section for more information). In the case of nested return fields, you can request specific fields of the subobject by concatenating them to the parent field using the ‘.’ (period) character.

For example, during a search for record:host, you can request the return of the ‘bootserver’ field in subobject ‘ipv4addrs’ by passing a return field in the form of ‘ipv4addrs.bootserver’. You can also specify subobject fields as part of a _return_fields+ invocation. In this case, the specified return field will be returned in addition to the standard fields for the specified subobject.

If an empty subobject field is passed, and the subobject field is a reference-only nest return field, it is equivalent to asking for the standard fields of that subobject. This can be useful if the subobject field returns only the reference of the subobject by default. For example, in the ‘permission’ object, the ‘object’ field normally contains only the reference of the object to which the permission applies. To request the standard fields for the object, you must explicitly reference the field name preceded by the keyword “object” and a period “.” For example, _return_fields=object.fqdn

If a field can support multiple object types, for example ‘record’ inside allrecords, only fields common to all the multiple object types should be specified as subobject fields. Otherwise if a subobject for which the subfield is not valid exists, an error would be returned.

Return Status/Errors

Status

Description

200

Normal return. Referenced object or result of search in body.

400

Results set would contain more than _max_results objects (only generated if _max_results is negative).

404

Referenced object not found (if objref form is used, empty list and 200 is returned for empty search result)

Results paging

For searches that return a large number of results, paging is desirable.

To start a paging request, the initial search request must have _paging and _return_as_object set to 1, and _max_results set to the desired page size.

The server will then return a results object that contains the next_page_id field and the result field set to the first page of results.

Note that the next_page_id field only contains URL-safe characters so it can be used as is and no quotation characters are required for subsequent requests.

To get more results, you should send GET requests to the original object and set _page_id to the ID string returned in the previous page of results.

The server does not return a next_page_id field in the last page of results. Paging requests are considered independent requests, so the set of results might change between requests if objects are added or removed from the server at the same time when the requests are occurring.

For an invocation example, see the sample code section in the manual here.

WAPI Schema Fetching

If the _schema option is passed, the request will execute a schema fetch. Other options, such as _max_results, _return_fields, etc., will be ignored.

The WAPI schema returned in the format requested using either the Accept: header or _return_type as specified by WAPI.

Note that this is not intended to be a schema as defined by JSON or XML standards.

If a WAPI schema is requested using the _schema option without specifying objtype, an object with the following fields will be returned:

Field

Description

requested_version

Actual requested version of the WAPI schema.

supported_objects

List of supported objects in the requested version.

supported_versions

List of all supported versions.

Example. Use a GET request to get the WAPI schema:

https://1.2.3.4/wapi/v1.0/?_schema

Returns with a body (lists shortened):

{ "requested_version": "1.0",
  "supported_objects": ["ipv4address", "ipv6address", "ipv6network",
                        "ipv6networkcontainer", "ipv6range",
                        "macfilteraddress", "network", ...],
  "supported_versions": ["1.0", "1.1", "1.2", "1.2.1", ...]
}

If the described above is done specifying _schema_version=2, then following field will be returned additionally:

Field

Description

schema_version

The version of schema description requested.

supported_schema_versions

List of supported versions for schema description.

Example:

https://1.2.3.4/wapi/v2.5/?_schema=1&_schema_version=2

Returns with a body (lists shortened):

{ "requested_version": "2.5",
  "schema_version": "2",
  "supported_schema_versions": ["1", "2",],
  "supported_objects": ["ad_auth_service", ... ],
  "supported_versions": ["2.3","2.5", ... ]
}

If the objtype is specified for WAPI schema fetching, an object with the following fields will be returned:

Field

Description

cloud_additional_restrictions

List of cloud restrictions.

fields

List of fields of the object.

restrictions

List of object restrictions.

type

Requested objtype.

version

Actual requested version of the WAPI object schema.

The fields specific to schema description #2:

Field

Description

schema_version

The version of schema description requested.

wapi_primitive

Determines if the requested WAPI primitive is object, structure or function call.

The list of object restrictions that contain supported operations for the object. Example of operations: “create”, “delete”, “read”, “update”, “function call”, “permissions”, “global search”, “scheduling”, “csv”.

The cloud_additional_restrictions field contains the list of additional unsupported operations when using Cloud Network Automation. Example of operations: “all”, “create”, “delete”, “read”, “update”, “function call”, “permissions”, “global search”, “scheduling”, “csv”.

The returned fields list is composed by individual objects each describing a field of the API object. These objects have the following members:

Parameter

Description

is_array

True if this field is an array.

name

Name of this field.

searchable_by

String with supported search modifiers: “=”, “!”, “:”, “~”, “<”, “>”.

standard_field

True for fields that are returned by default.

supports

List of supported operations: “s”, “w”, “u”, “r”.

type

List of supported types.

wapi_primitive

Determines if the requested WAPI primitive is object, structure or function call.

The fields specific to schema description #2:

Field

Description

schema_version

The version of schema description requested.

wapi_primitive

Determines if the requested WAPI primitive is object, structure or function call.

supports_inline_funccall

Determines if the field can be initialized by calling an inline function.

doc

The documentation of this field. It’s applicable only when _get_doc=1 is used. The returned documentation string might contain ReStructuredText directives.

The version #2 delivers all information regarding structures and function calls.

Please keep in mind that enum_values is changed in #2. It cannot be a dictionary, as it was in #2, but a list.

Example. Use a GET request to get the ‘networkview’ WAPI object schema for WAPI version 1.4:

https://1.2.3.4/wapi/v1.4/networkview?_schema

Returns with a body (lists shortened):

{ "cloud_additional_restrictions": ["all"],
  "fields": [{
      "is_array": false,
      "name": "comment",
      "searchable_by": ":=~",
      "standard_field": true,
      "supports": "rwus",
      "type": ["string"]
  }, {
      "is_array": false,
      "name": "name",
      "searchable_by": ":=~",
      "standard_field": true,
      "supports": "rwus",
      "type": ["string"]
  }, ...],
  "restrictions": ["scheduling", "csv"],
  "type": "networkview",
  "version": "1.4"
}

Example of new information for version #2 (the same request as above but differt objtype and HTTP arguments:

https://1.2.3.4/wapi/v2.13.6/grid?_schema=1&
  _schema_version=2&_get_doc=1

Returns with a body (lists shortened and cut):

{ "doc": "Test connectivity to the REST API endpoint.",
  "is_array": false,
  "name": "test_connection",
  "schema": {
  "input_fields": [],
  "output_fields": [
    { "doc": "The overall status of connectivity test.",
      "enum_values": [
        "FAILED",
        "SUCCESS"
      ],
      "is_array": false,
      "name": "overall_status",
      "supports": "r",
      "type": ["enum"]
    },
    { "doc": "The test connectivity failed error message.",
      "is_array": false,
      "name": "error_message",
      "supports": "r",
      "type": ["string"]
    }
  ]
  },
  "standard_field": false,
  "supports": "rwu",
  "type": ["testconnectivityparams"],
  "wapi_primitive": "funccall"
},
{ "doc": "The notification REST template instance. The parameters of
          REST API endpoint template instance are prohibited to
          change.",
  "is_array": false,
  "name": "template_instance",
  "schema": {
    "fields": [
      { "doc": "The name of REST API template parameter.",
        "is_array": false,
        "name": "template",
        "supports": "rwu",
        "type": ["string"]
      },
      { "doc": "The notification REST template parameters.",
        "is_array": true,
        "name": "parameters",
        "supports": "rwu",
        "type": ["notification:rest:templateparameter"]
      }
    ]
  },
  "standard_field": false,
  "supports": "rwu",
  "type": ["notification:rest:templateinstance"],
  "wapi_primitive": "struct"
},

WAPI Inheritance Data Fetching

If the _inheritance option is passed and set to True, the request will fetch inheritance data. Inheritance data will only show for fields which were queried and support this mode. Inheritance support started from version 2.10.2.

In case of basic inheritance, an object with following fields will be returned:

Field

Description

inherited

Flag to display whether value was inherited or not.

multisource

Flag to display if value was inherited from multiple sources.

source

String containing WAPI reference to source of data. Empty string if data belongs to a queried object.

value

Actual value.

Example. Use a GET request to get the ‘grid’ object’s ‘ipam_threshold_settings’ and inheritance info, if needed:

https://1.2.3.4/wapi/v2.10.3/network?_inheritance=True
        &_return_fields=ipam_threshold_settings

Output when object’s data is shown:

{
  "ipam_threshold_settings": {
    "inherited": false,
    "multisource": false,
    "source": "",
    "value": {
      "reset_value": 86,
      "trigger_value": 96
    }
  }
},

Output when inherited data is shown:

{
  "ipam_threshold_settings": {
    "inherited": true,
    "multisource": false,
    "source": "grid/b25lLmNsdXN0ZXIkMA:Infoblox",
    "value": {
      "reset_value": 85,
      "trigger_value": 95
    }
  }
},

In case of multiple inheritance, array of values with their sources will be shown. An object with following fields will be returned:

Field

Description

inherited

Flag to display whether value was inherited or not.

multisource

Flag to display if value was inherited from multiple sources.

values

List of structs, describing values, inherited from multiple source. Structure described below.

Structure of ‘values’ object:

Field

Description

source

String containing WAPI reference to source of data. Cannot be empty.

value

Actual value.

Example of query:

https://1.2.3.4/wapi/v2.10.3/network?_inheritance=True
        &_return_fields=pxe_lease_time

Output:

{
  "pxe_lease_time": {
    "inherited": true,
    "multisource": true,
    "values": [
      {
        "source": "grid:dhcpproperties/ZG5zLmNX9wZXJ0aWVzJDA:Infoblox",
        "value": 43200
      },
      {
        "source": "member:dhcpproperties/ZG5zMkMA:infoblox.localdomain",
        "value": 403200
      }
    ]
  }
},

In case if the object of inheritance is a list consisting of structs and every item of this list is inherited independently, items will be grouped by their sources. Some items may appear several times if they are inherited from multiple sources.

Structure of such groups is described below:

Field

Description

inherited

Flag to display whether value was inherited or not.

source

String containing WAPI reference to source of data. Empty string if data belongs to a queried object.

value

List of structs, inherited from given source.

Example of query:

https://1.2.3.4/wapi/v2.10.3/network?_inheritance=True
        &_return_fields=options

Output:

{
  "options": [
    {
      "inherited": true,
      "source": "member:dhcpproperties/ZG5zL1lByb3BlcnRpZXMkMQ:mem.ber",
      "values": [
        {
          "name": "subnet-mask",
          "num": 1,
          "value": "255.255.254.0",
          "vendor_class": "DHCP"
        }
      ]
    },
    {
      "inherited": true,
      "source": "member:dhcpproperties/ZG5zLXMkMA:infoblox.localdomain",
      "values": [
        {
          "name": "subnet-mask",
          "num": 1,
          "value": "255.255.255.0",
          "vendor_class": "DHCP"
        }
      ]
    },
    {
      "inherited": true,
      "source": "grid:dhcpproperties/ZG5zLmNXN0Z9wZXJ0aWVzJDA:Infoblox",
      "values": [
        {
          "name": "dhcp-lease-time",
          "num": 51,
          "use_option": False,
          "value": "43200",
          "vendor_class": "DHCP"
        }
      ]
    }
  ]
},

POST

Create Object: POST Method

The POST method is used to create a new object. It can also be used for all other operations via the the wapi object

Syntax

POST WAPI / objtype [ ? { options | field = value }… ]

Description

The data for the request must contain all required fields of the objtype. Data can be given as arguments as shown above or as the body of the request (but not both).

Options

Method Option

Description

_return_fields

A list of returned fields separated by commas. The use of _return_fields repeatedly is the same as listing several fields with commas. The default is the basic fields of the object.

_return_fields+

Specified list of fields (comma separated) will be returned in addition to the basic fields of the object (documented for each object).

_inheritance

If this option is set to True, fields which support inheritance, will display data properly.

Options can be given only as query arguments as shown above, they cannot be included in the body of the request.

Arguments

Arguments can be used to supply the object instead of using the body.

Data (Body)

Data for object to be created. Can be used as alternative to arguments. All fields marked as required for the object must be supplied. All fields not supplied will be defaulted as specified for the object. See Use Flags for information about special handling for these fields.

Data Returned

Object Reference of the object created, returned as a string.

If required, specify the ‘_return_fields’ option to examine the values of fields that were set by the appliance as part of the insertion. It is possible for the appliance to return the newly inserted object, instead of a reference string.

Passing an empty value to the ‘_return_fields’ option will cause only the object reference to be set inside the returned object. Passing an empty value to the ‘_return_fields+’ option will cause the returned object to contain its standard fields. Passing any other values will return the specified fields.

Return Status/Errors

Status

Description

201

Object created (success)

PUT

Update Object: PUT Method

The PUT method is used to update an existing object. The syntax of PUT is:

Syntax

PUT WAPI / objref [ ? { option | field = value }… ]

Description

PUT is used to update an existing object (given by the Object Reference, objref in the request). Only the fields supplied are updated (except as described for Use Flags).

Options

Method Option

Description

_return_fields

List of returned fields separated by commas. The use of _return_fields repeatedly is the same as listing several fields with commas. The default is the basic fields of the object.

_return_fields+

Specified list of fields (comma separated) will be returned in addition to the basic fields of the object (documented for each object).

_inheritance

If this option is set to True, fields which support inheritance, will display data properly.

Options can be given only as query arguments as shown above, they cannot be included in the body of the request.

Arguments

The data to be updated can be given as argument as shown in the syntax or as the body of the request (but not both).

Data (Body)

Data for object to be updated. Can be used as alternative to arguments.

Data Returned
Object Reference of the object modified, returned as a string.

The object reference may have been changed by the operation.

If required, specify the ‘_return_fields’ option to examine the values of fields that were set by the appliance as part of the update. It is possible for the appliance to return the newly updated object, instead of a reference string.

Passing an empty value to the ‘_return_fields’ option will cause only the object reference to be set inside the returned object. Passing an empty value to the ‘_return_fields+’ option will cause the returned object to contain its standard fields. Passing any other values will return the specified fields.

Return Status/Errors

Status

Description

200

Object updated (success)

DELETE

Delete Object: DELETE Method

The DELETE method is used to delete an object.

Syntax

DELETE WAPI / objref [ ? option… ]

Description

DELETE is used to delete an existing object (given by the Object Reference, objref in the request).

Options

There are no DELETE specific options.

Arguments

There are no general DELETE arguments. Some of the objects has object-specific DELETE arguments, which are described in the ‘Delete arguments’ section of their respective documentation.

Data Returned

Returns the Object Reference of the deleted object as a string.

Return Status/Errors

Status

Description

200

Object deleted (success)

Objects

Structs

Additional Information and Examples