Using the legacy Address Manager REST v1 API client - Platform - BlueCat Gateway - 23.1

Gateway Administration Guide

Locale
English
Product name
BlueCat Gateway
Version
23.1

Gateway's Address Manager REST v1 API clients provide access to the Address Manager Legacy v1 API. The REST v1 clients are intended for Gateway users who already have existing workflows that use the previous version of the Address Manager API.

Note: We recommend using the new Address Manager REST v2 API client where possible. You must be connecting to Address Manager 9.5 or later to use the REST v2 API client.

There are three REST v1 clients:

  • Standard API client: Also called the "Specification" client. This client consists of a set of "wrappers" for Address Manager REST v1 API endpoints. Each wrapper is associated with a specific component of the Address Manager API. When you call a wrapper from a Gateway workflow, it passes on the request to the associated component of the Address Manager API.

  • Object-oriented API client: This client accesses the Address Manager REST v1 API with an object-oriented approach. This approach treats clients, configurations, and other resources as objects, which can be useful in some circumstances.

  • "Raw" Address Manager API client (raw_api): This client makes calls to the Address Manager REST v1 API directly, using a "raw" client. This can be useful if you need to use a REST v1 API endpoint that does not yet have a corresponding wrapper in the Standard API client.

Where possible, BlueCat recommends using the Standard API client. The Object-oriented API Client does not support the same breadth of Gateway functionality as the Specification API client.

Note: The BAMAPI class provides access to both the Address Manager REST v1 and REST v2 clients. However, only one of the REST v1 client or the REST v2 client can be active on a single instance of Gateway.

Prerequisites

In order to access the Address Manager REST v1 API clients:

Using the standard REST v1 API client in scripts

To work with the Standard API client (so that you can access the Address Manager Legacy v1 API), use the BAMAPI class.

The standard Gateway Python API Client contains wrappers for most Address Manager API features. It is designed for use in Python scripts. To use this client in scripts, you must first import the appropriate libraries, then get an instance of the client through flask.g.user:
# Get the API client.
api = g.user.bam_api.v1
Note: This client, sometimes called the "Specification client" (or "spec_api"), originally used the following syntax:
api = g.user.get_api().spec_api
While this syntax will still work, we recommend using the updated syntax where possible.
You can then pass API calls and references through that client instance:
# Obtain a configuration with a specific name config_name, using the get_entity_by_name() function
configuration = api.get_entity_by_name(0, config_name, ObjectType.CONFIGURATION)
For example, the script below implements a Gateway endpoint that returns the names and addresses of servers under a given BAM configuration:
from flask import g, jsonify

from main_app import app
from bluecat import route
from bluecat_libraries.address_manager.constants.object_type import ObjectType
from bluecat_libraries.http_client.exceptions import ErrorResponse


@route(app, "/get-servers/<string:config_name>", methods=["GET"])
def get_servers(config_name):

    # Get the API client.
    api = g.user.bam_api.v1

    try:
        # Obtain the configuration with the given name.
        configuration = api.get_entity_by_name(0, config_name, ObjectType.CONFIGURATION)
        if configuration is None:
            return "Configuration does not exist", 404

        # Obtain servers under the given configuration.
        servers = api.get_entities(configuration["id"], ObjectType.SERVER)

    # If something goes wrong, the API client typically raises `ErrorResponse`. Catch it to handle errors.
    except ErrorResponse as e:
        return e.message, 500

    # Return server names and addresses.
    return jsonify(
        [
            {"name": server["name"], "address": server["properties"]["servicesIPv4Address"]}
            for server in servers
        ]
    )

Using the object-oriented API client

Some GatewayAPI operations can be accessed with an object-oriented approach. This approach treats clients, configurations, and other resources as objects, which can be useful in some circumstances.
Note: Where possible, BlueCat recommends using the standard API client instead. The Object-oriented API Client does not support the same breadth of Address Manager and BDDS functionality as the standard client.
from flask import g, jsonify

from main_app import app
from bluecat import route
from bluecat.api_exception import APIException


@route(app, "/get-servers/<string:config_name>", methods=["GET"])
def get_servers(config_name):

    # Get the Object-Oriented API client.
    api = g.user.get_api()

    try:
        # Obtain the configuration with the given name.
        configuration = api.get_configuration(config_name)

        # Obtain servers under the given configuration.
        servers = configuration.get_servers()

    # If something goes wrong, the Object-Oriented API client typically raises `APIException`. Catch it to handle errors.
    except APIException as e:
        return e.get_message(), 500

    # Return server names and addresses.
    return jsonify(
        [
            {"name": server.name(), "address": server.get_service_ip4_addresses()[0]}
            for server in servers
        ]
    )

Using the raw API to access the Address Manager REST v1 API directly (raw_api)

The Standard Gateway API provides wrappers for most Address Manager API methods, classes, and other references. To use the Gateway API with those wrappers, use the standard API (see Using the legacy Address Manager REST v1 API client).

If you need to use an Address Manager REST v1 API endpoint that does not yet have a corresponding wrapper in the Python API client, you can use the Python API client to make calls to that endpoint directly, using a "raw" client. Below is the same get-servers example reworked to make such calls:

from flask import g, jsonify

from main_app import app
from bluecat import route
from bluecat_libraries.address_manager.constants.object_type import ObjectType
from bluecat_libraries.http_client.exceptions import ErrorResponse


@route(app, "/get-servers/<string:config_name>", methods=["GET"])
def get_servers(config_name):

    # Get the raw client.
    api = g.user.get_api().raw_api

    try:
        # Obtain the configuration with the given name.
        configuration = api.getEntityByName(parentId=0, name=config_name, type=ObjectType.CONFIGURATION)
        if configuration["id"] == 0:
            return "Configuration does not exist", 404

        # Obtain up to 10 servers under the given configuration.
        servers = api.getEntities(parentId=configuration["id"], type=ObjectType.SERVER, start=0, count=10)

    # If something goes wrong, the raw client typically raises `ErrorResponse`. Catch it to handle errors.
    except ErrorResponse as e:
        return e.message, 500

    # Extract server names and addresses.
    out = []
    for server in servers:
        # The `getEntities` method returns properties as a string of the form `k1=v1|k2=v2|...`
        for kv in server["properties"].split("|"):
            k, v = kv.split("=", maxsplit=1)
            if k == "servicesIPv4Address":
                out.append({"name": server["name"], "address": v})
                break

    return jsonify(out)
-