Skip to content

README.md

Latest commit

 

History

History
128 lines (96 loc) · 7.28 KB

README.md

File metadata and controls

128 lines (96 loc) · 7.28 KB

LANforge HTTP API Python Library

This Python library provides a set of generated methods, classes, and utilities to operate the LANforge HTTP API. A brief overview of the HTTP API and Telnet CLI can be found here.

At a high level, this library consists of wrappers around the LANforge CLI, enabling users to query and configure LANforge systems/testbeds without effort spent writing tedious boilerplate code. Components of this library invoke the HTTP API by performing HTTP GETs and HTTP POSTs to HTTP endpoints presented by the HTTP API. As detailed here, the HTTP API endpoints correspond 1:1 with LANforge GUI tabs. HTTP GETs query system state and return JSON data. HTTP POSTs configure system state and send JSON data when using this library (however, the HTTP API also supports HTTP POSTs with URL-encoded data as well).

If you are new to this API, please start at the beginning of the LANforge Scripting Cookbook. Simpler example scripts which use this library are available here, in addition to more complex scripts in py-scripts/.

Requirements

  • LANforge 5.4.5 or newer

  • LANforge GUI active during usage of automation

    • The LANforge GUI runs the HTTP API, so it must be active in order to use most automation
    • Details on how to configure the LANforge GUI on a pre-installed system are available in this cookbook

  • LANforge Scripts/Automation Installation Setup complete

    • See the setup instructions here

Features

This Python library provides a set of generated methods, classes, and utilities to operate the LANforge HTTP API.

A brief listing of available library code is as follows:

  • lanforge_api.py
    • Contains the core Python library including classes to configure and query LANforge systems
    • LFSession
      • Provides a session abstraction for querying/configuring the LANforge system
      • Additionally provides diagnostic tracing and callback IDs for specific types of CLI commands
    • LFJsonQuery
      • Defines HTTP GET requests to query the LANforge system
      • Available endpoints are visible by performing a GET request to the root endpoint or navigating to that endpoint in your browser
        • e.g. http://192.168.1.101:8080/
      • Each endpoint contains a corresponding get_xxx() method. For example, /ports can be queried by calling get_port().
    • LFJsonCommand
      • Defines HTTP POST requests to configure the LANforge system
      • Each method corresponds to a respective CLI command
      • Helper classes define flags and types which the CLI commands require
      • For example, the add_sta CLI command can be configured using post_add_sta().
  • logg.py
    • Logg class and helper methods to configure LANforge API logging for LFJsonQuerys and LFJsonCommands.
  • strutil.py
    • Helper functions for working with strings

Intended Usage

Suggested Workflow

Generally, the workflow for a script using LANforge API will look something like:

  1. Import lanforge_client
  2. Initiate a LFSession
  • Ensure the script URI is directed at the manager LANforge for your testbed (should your testbed have more than one LANforge)
  • Also make sure that the GUI is running. To configure the GUI to automatically start, see this cookbook in the documentation.
  1. Use a combination of LFJsonCommand to configure or LFJsonRequest to query the LANforge, respectively.

Things to Keep in Mind

This library can be used directly, plus it can be used in conjunction with the LANforge Realm class. It is different than than the Realm class. Realm extends the lfcli_base class that provides its own (nearly identical) REST API. The lanforgeclient REST methods are built into the _BaseLFJsonRequest class.

You would use the Realm class to execute high-level operations like:

  • creating groups of stations
  • creating numerous connections
  • reporting KPI events like test results

You would use the lanforge_client package in places where:

  • you want direct LANforge CLI control that hides the URLs
    • port specific flags
    • endpoint specific flags
  • to get session tracking and using callback keys
  • you want an API that hides the REST URLs

The Realm class is useful. As the lanforge_client package stabilizes, we anticipate replacing lower level parts of the Realm based operations to call into the lanforge_client package.

Getting started

NOTE: Example scripts are located in the examples/ directory. See the README.md for more information on available examples.

Below is an example of instantiating a LFSession object and getting the LFJsonQuery (for GETs) and LFJsonCommand (for POSTs).

import lanforge_api
import lanforge_api.LFJsonCommand
import lanforge_api.LFJsonQuery

def main():
    session = lanforge_api.LFSession(lfclient_url="http://%s:8080" % args.host,
                                     debug=args.debug,
                                     connection_timeout_sec=2.0,
                                     stream_errors=True,
                                     stream_warnings=True,
                                     require_session=True,
                                     exit_on_error=True)
    command: LFJsonCommand
    command = session.get_command()
    query: LFJsonQuery
    query = session.get_query()

    command.post_rm_text_blob(p_type=args.type, name=args.name,
                              debug=args.debug, suppress_related_commands=True)
    command.post_show_text_blob(name='ALL', p_type='ALL', brief='yes')
    command.post_add_text_blob(p_type=args.type, name=args.name, text=txt_blob,
                               debug=True, suppress_related_commands=True)
    command.post_show_text_blob(name='ALL', p_type='ALL', brief='no')
    eid_str="%s.%s" % (args.type, args.name)
    print ("List of text blobs:")
    diagnostics=[]
    result = query.get_text(eid_list=eid_str, debug=True, errors_warnings=diagnostics)
    pprint.pprint(diagnostics)
    pprint.pprint(result)