Skip to content

Training

💡 Lab-Focused Training

Instead of hours of concepts, many propose that training be organzied around a series of Labs. This page outlines such a course, presuming:

  • WebGenAI-focused
  • Java background - new to Python

Initial Background

Review the GenAI Architecture, and take a quick scan of Python for Java programmers.

Installation and Configuration

While WebGenAI is available via your browser - you will want to have a local version of Python, ApiLogicServer, VSCode (and optionally Docker Desktop) running. This has been documented here:

  1. Python 3.12 Installation
  2. Understand Virtual Environments, and als notes
  3. ApiLogicServer Installation
  4. VSCode for Python
  5. Docker Desktop Install
  6. Sample Docker Databases are available for learning.

 

Core WebGenAI

In this series of labs, you will

  1. create and run projects
  2. debug them, both in WebGanAI and the IDE
  3. explore iterations

 

Using WebGenAI in the Browser

You can run WebGenAI locally on your desktop or your company may have a cloud version running. WebGenAI uses OpenAI ChatGPT and requires the configuration of both a license and an OpenAI API Key. Watch the video here

In this lab:

  1. Create the demo project from a prompt Prompt Engineering Basics
  2. Verify the logic by navigating to a Customer with an unshipped order, and altering one of the items to have a very large quantity
  3. Explore debugging logic using your Browser

 

Using your IDE

Download (aka Export)

The web-based interface is great for rapid creation, but you will enjoy much better debugging using your IDE. We'll explore that in these next labs.

Please see Export.

Use the 'Project Download' link from the '2> develop' page or the project page (as a tar file). Unzip or un-tar the file and copy to the manager or developer workspace.

 

Start the Manager

The Manager is a pre-configured VSCode with samples used to help new developers learn about ApiLogicServer. See the Manager documentation.

See the procedure below (cd ApiLogicServer; code .)

 

Copy your Project to the Manager Directory

As explained in Export.

 

Start your project

The Manager has a readme which explains how to run projects from inside the manager. When you are getting started, it's easiest just to launch another instance of VSCode. In the termimal window of VSCode:

cd <your project>
code .

 

Explore Logic Debugging

Refer to the docs on logic debugging.

  1. Put a breakpoint on the constraint
  2. Start the Server (F5)
  3. Start the App in the Browser
  4. Verify the logic by navigating to a Customer with an unshipped order, and altering one of the items to have a very large quantity * Observe the log, showing each rule firing with the row data

 

Explore Rule Concepts

ApiLogicServer provides a rule engine (LogicBank) to allow the developer to add derivations, constraints and events to any API endpoint. These rules can be created by WebGenAI natural language or using the VSCode IDE manually entered.

  1. Rule Type Patterns

 

WebGenAI Iterations

Explore WebGenAI iteration services:

  1. Use the 'Iterate' button to modify the created project
  2. Use the 'Logic' button and the 'Suggestion' to create natural language rules
  3. Use the 'Update Model' button if the rules fail to activate

 

Dev Strategy: WebGenAI, IDE, or Both?

You will find WebGenAI remains useful, particularly for updating the data model (e.g., as required for logic). The system provides Import/Merge services to sync WebGenAI changes with IDE changes.

If you elect to focus on IDE development, analogous services are provided with Rebuild from Model / Database, and Alembic support.

 

Concepts and Facilities

Command Line Basics

The command line (cli) is the key to use all of the features of ApiLogicServer. Note that each command may have a set of additional arguments: use --help to see the additional features (e.g. als genai --help).

als --help
Welcome to API Logic Server {version}

Usage: als [OPTIONS] COMMAND [ARGS]...

      Creates [and runs] logic-enabled Python database API Logic Projects.

          Creation is from your database (--db-url identifies a SQLAlchemy database)

          Doc: https://apilogicserver.github.io/Docs
          And: https://apilogicserver.github.io/Docs/Database-Connectivity/

      Suggestions:

          ApiLogicServer start                                # create and manage projects
          ApiLogicServer create --db-url= --project-name=     # defaults to Northwind sample


Options:
  --help  Show this message and exit.

Commands:
  about                  Recent Changes, system information.
  add-auth               Adds authorization/authentication to curr project.
  add-cust               Adds customizations to northwind, genai,...
  add-db                 Adds db (model, binds, api, app) to curr project.
  app-build              Builds runnable app from: ui/<app>/app-model.yaml
  app-create             Creates Ontomize app model: ui/<app>/app-model.yaml
  create                 Creates new customizable project (overwrites).
  create-and-run         Creates new project and runs it (overwrites).
  create-ui              Creates models.yaml from models.py (internal).
  curl                   Execute cURL command, providing auth headers...
  curl-test              Test curl commands (nw only; must be r)
  examples               Example commands, including SQLAlchemy URIs.
  genai                  Creates new customizable project (overwrites).
  genai-create           Create new project from --using prompt text.
  genai-iterate          Iterate current project from --using prompt text.
  genai-logic            Adds (or suggests) logic to current project.
  genai-utils            Utilities for GenAI.
  login                  Login and save token for curl command.
  rebuild-from-database  Updates database, api, and ui from changed db.
  rebuild-from-model     Updates database, api, and ui from changed models.
  run                    Runs existing project.
  start                  Create and Manage API Logic Projects.
  tutorial               Creates (updates) Tutorial.
  welcome                Just print version and exit.
  1. Explore cli create, add-auth, app-build, app-create, rebuild-from-database
  2. GenAI cli

 

Connect to SQL

If the project has an existing SQL DBMS (MySQL, PostgreSQL, SQL Server, Oracle) - ApiLogicServer can connect to SQL and build a detailed API. Review the documentation of Data-Model design, examples, keys, quoted identifiers, etc. In this lab - we will connect to the northwind database. 

als create --project-name=myproject --db-url=nw+
cd myproject
code .
Open database/models.py

  1. Data-Model-Design
  2. Primary Keys on each table
  3. Relationships (foreign keys) many-to-one (parent), one-to-many (children) (or many-to-many)
  4. Accented characters (als create --db-url=... --quote) quoted identifiers
  5. SQLAlchemy ORM model.py
  6. Run Server (F5) with or without security
  7. Start React Application (http://localhost:5656)
  8. Review OpenAI (Swagger) (http://localhost:5656/api) JSON API

 

Integration

Some applications may require integration with other services (e.g. email, payment, workflow, etc) In this lab - explore how to use the existing services to integration with Kafka or Workflow.

  1. Integration and Configuration Kafka
  2. Send a message to Kafka (event driven) by topic
  3. Listen for incoming Kafka message by topic
  4. Integration with Workflow (n8n) - Using WebHooks
  5. Configuration of Kafka or n8n (config.py)

Ontimize Angular Application

OntimizeWeb from Imatia is an Angular application that is automatically created from the command line. In this lab - review the Ontimize process here

Start ApiLogicServer first (note: must enable security: als add-auth --provider-type=sql) 

als app-create --app=app
als app-build --help
 example:

      ApiLogicServer app-build —app=name=app1

      ApiLogicServer app-build —app=name=app1 —api-endpoint=Orders 
      # only build Orders          This creates app1/app-model.yml. 

Options:
  --project-name TEXT  Project containing App
  --app TEXT           App directory name
  --api-endpoint TEXT  API endpoint name
  --template-dir TEXT  Directory of user defined Ontimize templates
  --help               Show this message and exit.


als app-build --app=app
cd ui/app
npm install && npm start  # http://localhost:4299

  1. Create an Ontimize application
  2. Build (rebuild) Ontimize Application or Page
  3. Yaml File Basics
  4. Working with Templates
  5. Application Model Editor
  6. Advanced Filters (enable)

Note: This version uses the Ontimize API Bridge - work is being done to use JSON API

 

Configure Security

The ability to secure your application is an important part of the creation of any API Microservice application. In this lab - review and try:

  1. Who Can Access - Authentication
  2. What can they Do - Authorization (role-based access control)
  3. Use KeyCloak local docker image
  4. Use SQL login

Deployment (devops)

ApiLogicServer has a suite of tools for devops to build and deploy Docker containers.

  1. Build a Docker Image

 

Adv Project

  1. Adding attributes if they are not added automatically
  2. SQLIte to PostgreSQL migration (sqlite3 db.sqlite .dump > postgres.sql)
  3. Rebuild test data (?)

 

Be Aware Of

  1. Behave Testing (optional)
  2. Alembic Schema Migration

 

Appendices

Start the Manager

The Manager is a pre-configured VSCode with samples used to help new developers learn about ApiLogicServer. See the Manager documentation.

Recall you installed the manager when you installed API Logic Server. In a terminal window or powershell:

mkdir ApiLogicServer
cd ApiLogicServer
python -m venv venv
source venv/bin/activate      # windows: venv\Scripts\activate
pip install ApiLogicServer
ApiLogicServer start

Explore the NorthWind (nw) example to learn about ApiLogicServer. Each folder represents a key concepts (e.g. config, api, database, logic, security, devops, test, ui)

Later, when you exit VSCode, you can restart the Manager:

cd ApiLogicServer
code .

 

 

Explore the folders
  1. Config/config.py - runtime settings
  2. Database/models.py - SQLAlchemy ORM
  3. Api/custom_api.py - Custom API endpoints
  4. logic/declare_logic.py
  5. security declare_security.py and security/system/authentication.py
  6. devops containers - various docker scripts
  7. ui/admin admin.yaml - React back office
  8. test - behave testing