API class - Platform - BlueCat Gateway - 18.2.1

Gateway Administration Guide
prodname
BlueCat Gateway
version_custom
18.2.1

The API class is the main entry point into the BlueCat API. Most use cases involve instantiating an API instance, connecting to BAM, and going from there.

An example is as follows:

#!/usr/bin/python
from bluecat import api, api_exception

try:

    # Create a connection - the URL is the same one as used for raw BAM REST API connections.
    conn = API('http://192.168.56.191/Services/REST/application.wadl')

    # Log in using an API user configured via the BAM UI.
    conn.login('admin', 'admin')

    c = conn.get_configuration('Configuration Name')
    for s in c.get_servers():

        # Print the server name and any service IP4 addresses it has.
        print s.name(), s.get_service_ip4_addresses()

except APIException as e:
    # Something went wrong.
    print e.get_message()

some code

This is the main entry point for the API. The most common usage pattern is to create a connection via instantiation, login with the login method, then retrieve a configuration object via get_configuration or get_configurations.

classapi.API(url, sslverify=False, ca_file=None, ca_path=None, logger=None)

Bases: object

Create a connection to the BAM API.

Parameter Description
url URL of the BAM API (can be http or https).
sslverify Whether or not to verify the certificate installed on the BAM. Will generally be false for self signed certificates.
ca_file Name of the file listing CA’s for use in verification.
ca_path CA path used for verification.
add_default_access_right(recipient_id, value, overrides='', properties='')
Parameter Description
recipient_id The object ID of the user or user group the access right is applied to
value The value of the access right being added.
overrides A list of type-specific overrides.
properties

A string including the following options:

  1. workflowLevel
  2. deploymentAllowed
  3. quickDeploymentAllowed

Returns: Object ID of a created Access Right.

API Call:

delete_configuration(name='', entity_id=0)

Delete a configuration using name or id. Does not need both.

Parameter Description
name The name of the BAM configuration.
entity_id The object ID of the configuration in the BAM database.

API Call:

delete_group(name='', entity_id=0)

Delete a group, accepts either the group’s name or id.

Parameter Description
name The name of the BAM user group.
entity_id The object ID of the configuration in the BAM database.

API Call:

delete_user(name='', entity_id=0)

Delete a user, can use either username or id to specify which user to delete.

Parameter Description
name The name of the BAM user.
entity_id The object ID of the configuration in the BAM database.

API Call:

get_default_access_right(recipient_id)

Get an Access Right API Object. :param recipient_id: The object ID of the user or user group the access right is applied to. :return: Access Right object

API Call:

get_aliases_by_hint(hint, retrieve_fields=True)

Get a list of alias records that matches hint.

Parameter Description
hint The following wildcards are supported in the hint option:
  • ^-matches the beginning of a string. For example: ^ex matches example but not text.

  • $-matches the end of a string. For example: ple$ matches example but not please.

  • ^ $-matches the exact characters between the two wildcards. For example: ^example$ only matches example.

  • ?-matches any one character. For example: ex?t matches exit.
  • *-matches one or more characters within a string. For example: ex*t matches exit and excellent.
retrieve fields Boolean input. Will not include UDFs in results if False.

Returns: A List of alias_records.

API Call:

get_all_used_locations()

Returns an array of all used locations found in BAM (not per configuration).

Returns: Returns an array of all used locations; returns an empty list if no results are found.

API Call:

get_by_object_types(pattern, types)

Gets objects based on a search pattern and a list of object types.

Parameter Description
pattern Search pattern string (will match any of the various properties of a BAM entity).
types List of BAM entity types (For example, [entity.View, entity.Configuration]).

Returns: An iterator for objects found that match the pattern and types. Only the consistency of the first 1000 results can be guaranteed.

API Call:

get_configuration(name)

Get a named configuration.

Parameter Description
name Name of the BAM configuration.

Returns: configuration object of the named configuration.

API Call:

get_configurations(name)

Get all configurations.

Returns: Iterator of configuration objects. Only the consistency of the first 1000 results are guaranteed.

API Call:

get_country_locations()

Returns an iterator for all parent locations (countries) found in BAM (not per configuration).

Returns: An iterator for all country locations. Only the consistency of the first 1000 results are guaranteed.

API Call:

get_entity_by_id(entity_id)

Get an entity by its ID. The returned object is of the correct class, or if none is defined, is an entity instance.

Parameter Description
entity_id BAM entity ID (note that these are unique across all configurations).

Returns: Returns objects from the database referenced by their database ID and with its properties fields populated.

API Call:

get_group(group_name)

Get Group :param group_name: Group name :return: User Group

API Call:

get_location_by_code(code)

Use this method to get the location object with the specified hierarchical location code.

Parameter Description
code The hierarchical location code, it consists of a set of 1 to 3 alpha-numeric strings separated by a space. The first two characters indicate a country, followed by next three characters which indicate a city in UN/LOCODE. New custom locations created under a UN/LOCODE city are appended to the end of the hierarchy. For example, CA TOR OF1 indicates:
CA
Canada
TOR
Toronto
OF1
Office 1
Note: The code is case-sensitive. It must be all UPPER CASE letters. The county code and child location code should be alphanumeric strings.

Returns: The location entity object that corresponds to the location code.

API Call:

classmethodget_portal_version(folder_path=None)

Get the version of the API DNS Integrity Gateway.

API Call:

get_system_info()

Get current system information of the BAM server.

Returns: Returns BAM system information in the form of a name/value pair dictionary.

API Call:

get_tag_group_by_name(name)

Get a named tag group.

Parameter Description
name Name of the tag group.

Returns:A tag group entity object with given name.

API Call:

get_tag_groups()

Returns an iterator of tag groups found in BAM (not per Configuration).

Returns: An iterator of all tag.TagGroup objects. Only the consistency of the first 1000 results are guaranteed.

API Call:

get_url()

Get the URL of the application.

API Call:

get_user(username)

Get a named user.

Parameter Description
username Username of the BAM user.

Returns: user object for the username.

API Call:

get_version()

Get current system version from the system information as <major version>.<minor version>.<patch>.

Returns: Version string. eg. ‘8.0.0’.

API Call:

instantiate_entity(e)

Instantiate an appropriate Python class given an entity returned from a SOAP call.

Parameter Description
e SOAP entity.

Returns: A type specific instance object of the SOAP entity or generic entity object. None if there is no type.

API Call:

login(username, password)

Login to the BAM API using the supplied username and password. The user must be set up with API access via the BAM GUI. All normal permissioning applies.

Parameter Description
username BAM username.
password BAM password.

API Call:

logout()

Logout from the BAM API.

API Call:

print_bam_soap_methods()

Print details of the various BAM SOAP API methods to stdout. Useful for debugging purposes.