Tutorial

Welcome to this Tutorial

Use this Tutorial for a quick tour of API Logic Server

• Instant project creation from a database
• Fully customizable, using both standard code (Flask/SQLAlchemy) in your IDE, and
• Logic -- multi-table derivation and constraint logic using unique spreadsheet-like rules

This contains several projects. These projects use the Northwind Sample Database (customers, orders, products).

Project	What it is	Use it to...
1. Instant_Creation	Northwind Database - Uncustomized	Explore automated project creation from Database
2. Customized	Northwind Database - Customized	Explore customizing with code
3. Logic	Northwind Database - Customized, with Logic	Explore customizing with code, and rule-based logic
Next Steps	Create other sample databases	More examples - initial project creation from Database

 

If you are running via pip install (not Docker or Codespaces), you need to setup your virtual environment.

 

0. App_Fiddle: Manually Coded -- Learn Flask / SQLAlchemy - Fully customizable, but slow

This first app (0. App_Fiddle) illustrates a typical framework-based approach for creating projects - a minimal project for seeing core Flask and SQLAlchemy services in action. Let's run/test it, then explore the code.

To run, use the Run Configuration, and test with cURL.

   Show me how

 

To run the basic app:

1. Click Run and Debug (you should see *0. App Fiddle), and the green button to start the server

2. Copy the cURL text, and paste it into the bash/zsh window

3. When you have reviewed the result (here's the readme), stop the server

 

   --> Fully Customizable, but Faster Would Be Better

 

Frameworks are flexible, and leverage your existing dev environment (IDE, git, etc). But the manual effort is time-consuming, and complex. This minimal project does not provide:

• an API endpoint for each table

  • We saw above it's straightforward to provide a single endpoint. It's quite another matter -- weeks to months -- to provide endpoints for all the tables, with pagination, filtering, and related data access. That's a horse of an entirely different feather.
    
    

• a User Interface

• any security, or business logic (multi-table derivations and constraints).

Instead of frameworks, we might consider a Low Code approach. Low Code tools provide excellent custom user interfaces. However, these often require extensive screen painting, and typically require a proprietary IDE.

And neither frameworks nor Low-Code address multi-table derivation and constraint logic. This is typically nearly half the effort.

The next section introduces an approach that is as flexible as a framework, but faster than Low Code for APIs and Admin Apps.

 

1. Instant Creation -- Flexible as a Framework, Faster than Low Code

The 1. Instant_Creation app illustrates an alternative, creating an entire project by reading your schema. This automated approach is:

• Instant: faster than Low Code screen painting, with instant APIs and Admin User Interfaces:

  • Admin UI: multi-page / multi-table apps, with page navigations, automatic joins and declarative hide/show. No HTML or JavaScript required. Ready for Agile collaboration.

    • Custom UIs can be built using your tool of choice (React, Angular, etc), using the API
      
      

  • API: an endpoint for each table, with filtering, sorting, pagination and related data access. Swagger is automatic. Ready for custom app dev.

• Fully Customizable: with standard dev tools. Use your IDE, Python, and Flask/SQLAlchemy to create new services. We'll see several examples below.

• Open Source: install with pip or docker.

To execute (see Show me how, below, for details): start the server with Run and Debug >> 1. Instant Creation, and then start the Browser at localhost:5656 (url in the console log)

   Show me how

 

 

This application was not coded - it was created using the API Logic Server CLI (Command Language Interface), with 1 command (not necessary to do now - it's already been done):

cd tutorial
ApiLogicServer create --db_url=sqlite:///sample_db.sqlite --project_name=nw

If you do want to execute: stop the server, restart with Run and Debug >> nw, and then start the Browser at localhost:5656 (url in the console log).

 

Key Takeway: you will achieve this level automation for your projects: provide a database, get an instant API and Admin App. Ready for agile collaboration, custom app dev. Then, customize in your IDE.

 

   What is API Logic Server

 

What is Installed

API Logic server installs with pip, in a docker container, or in codespaces. As shown below, it consists of a:

• CLI: the ApiLogicServer create command you saw above
• Runtime Packages: for API, UI and Logic execution
  

 

Development Architecture

It operates as shown below:

• A) Create your database as usual

• B) Use the CLI to generate an executable project

  • The system reads your database to create an executable API Logic Project

• C) Customize and debug it in VSCode, PyCharm, etc.

 

Standard, Scalable Modern Architecture

• A modern 3-tiered architecture, accessed by APIs
• Logic is automatically reused, factored out of web apps and custom services
• Containerized for scalable cloud deployment - the project includes a dockerfile to containerize it to DockerHub.

 

   --> Instant, But Customization Required

 

An instant Admin App and API are a great start, but there are some significant short-comings:

• Limited endpoints - we may require additional endpoints beyond those automatically created

• No security - no login authentication

• No logic - multi-table derivations and constraints for save logic

  • For example, open Customer (left nav menu), click ALFKI, and EDIT > DELETE the first Order. Re-click Customer from the left nav menu - it should have reduced the customer's balance from 2102, but it's unchanged. That's because there is no logic...

  • Backend update logic can be as much as half the effort, so we really haven't achieved "Low Code" until this are addressed.

Let's see how these are addressed, in the next sections.

 

2. Customized -- Admin App, New Endpoint... Standard Dev Tools

Customizations are addressed using your IDE, using Standard use Flask and SQLAlchemy, exactly as you normally do.

Customizations are illustrated in the project 2. Customized. To see the effect of the changes, run the app like this:

1. Stop the server using the red "stop" button.
2. Restart the server with the same procedure as Step 1, above, but choose Run Configuration 2. Customized.
   

       Remind me how

 

1. Restart the Server:

   1. Click Run and Debug
   2. Use the dropdown to select 3. API Logic Project: Logic, and
   3. Click the green button to start the server
      
      

2. Start the Browser at localhost:5656, using the url shown in the console log

 

This project is the customized version of 1. Instant_Creation, above. The table below lists some of the key customizations you can explore.

 

Explore Key Customizations

Explore customizations in project: 2. Customized
Click Explore Code to see the code.
TL;DR - scan code marked by <--

Customization Area	Try It	Click to Explore Code	Notes
New API endpoint <--	curl -X GET "http://localhost:5656/filters_cats"	api/customize_api.py	Standard Flask/SQLAlchemy
Admin App <--	Observe help text describes features	ui/admin/admin.yaml	Not complex JS, HTML

 

 

3. Logic -- Unique Spreadsheet-like Rules (40X more concise), Plus Python

In addition to standard Flask/SQLAlchemy use, you can declare rules for multi-table derivations and constraints. Declare rules using Python as a DSL, leveraging IDE support for type-checking, code completion, logging and debugging.

Rules are extensible using standard Python. This enables you to address non-database oriented logic such as sending mail or messages.

Rules operate like a spreadsheet

Rules plug into SQLAlchemy events, and execute as follows:

Logic Phase	Why It Matters
Watch for changes at the attribute level	Performance - Automatic Attribute-level Pruning
React if referenced data is changed	Ensures Reuse - Invocation is automatic Derivations are optimized (e.g. adjustment updates - not aggregate queries)
Chain to other referencing data	Simplifies Maintenance - ordering is automatic

 

Customizations are illustrated in the project 3. Logic. To see the effect of the changes, run the app like this:

1. Stop the server using the red "stop" button.
2. Restart the server with the same procedure as Step 2, above, but choose Run Configuration 3. Logic.
   

       Remind me how

 

1. Restart the Server:

   1. Click Run and Debug
   2. Use the dropdown to select 3. API Logic Project: Logic, and
   3. Click the green button to start the server
      
      

2. Start the Browser at localhost:5656, using the url shown in the console log

 

This project further customizes 2. Customized, above. The table below lists some of the key customizations you can explore.

 

Explore Key Customizations

Explore customizations in project: 3. ApiLogicProject_Logic
Click Explore Code to see the code.
TL;DR - scan code marked by <--

Customization Area	Try It	Click to Explore Code	Notes
New API endpoint <--	Use Swagger for endpoint: CategoriesEndPoint/get_cats See docs - authenticate as u1	api/customize_api.py	Standard Flask/SQLAlchemy
Multi-table Update Logic <--	Delete Order now adjusts the customer balance	logic/declare_logic.py	Spreadsheet-like rules
Admin App <--	Observe help text describes features	ui/admin/admin.yaml	Not complex JS, HTML
Login Authentication	Click Category - observe you need to login now (user u1, password p)	config.py	See SECURITY_ENABLED
Role-Based Authorization	Observe categories has fewer rows	security/declare_security.py

 

Use the Detailed Tutorial to further explore this app.

 

 

Key Takeaways: Instant App/API, Fully Flexible, Unique Declarative Rules

You have seen the fastest and simplest way to create modern, scalable API-based database systems:

1. Use the ApiLogicServer create command to create a Flask/SQLAlchemy project from your database. Zero learning curve. Projects are instantly executable, providing:

   • an Admin App: multi-page, multi-table apps -- ready for business user agile collaboration
   • an API: end points for each table, with filtering, sorting, pagination and related data access -- ready for custom app dev
     
     

2. Open Flexibility: leverage standards for development and deployment:

   • Dev: customize and debug with standard dev tools. Use your IDE (e.g. VSCode, PyCharm), Python, and Flask/SQLAlchemy to create new services. Manage projects with GitHub.

   • Deploy: containerize your project - deploy on-premise or to the cloud (Azure, AWS, etc).

   • Flexible as a framework, Faster then Low Code for Admin Apps

3. Declare security and multi-table constraint/validation logic, using declarative spreadsheet-like rules. Addressing the backend half of your system, logic consists of rules, extensible with Python event code.

   • 40X more concise than code - unique to API Logic Server
     
     

 

 

Next Steps: New Projects

As shown above, it's easy to create projects with a single command. To help you explore, ApiLogicServer provides several pre-installed sqlite sample databases:

cd tutorial

ApiLogicServer create --db_url=sqlite:///sample_db.sqlite --project_name=nw

# that's a bit of a mouthful, so abbreviations are provided for pre-included samples
ApiLogicServer create --project_name=nw --db_url=nw-                       # same sample as 2, above
ApiLogicServer create --project_name=chinook --db_url=chinook              # artists and albums
ApiLogicServer create --project_name=classicmodels --db_url=classicmodels  # customers, orders
ApiLogicServer create --project_name=todo --db_url=todo                    # 1 table database

Then, restart the server as above, using the pre-created Run Configuration for Execute <new project>.

Next, try it on your own databases: if you have a database, you can have an API and an Admin app in minutes.

 

SQLAlchemy url required for your own databases

 

The system provides shorthand notations for the pre-installed sample databases above. For your own databases, you will need to provide a SQLAlchemy URI for the db_url parameter. These can be tricky - try ApiLogicServer examples, or, when all else fails, try the docs.

 

Click here for the docs.

 

Notes

 

Project Structure

This tutorial is actually 3 independent projects. When you create a project using ApiLogicServer create --project_name=my_project, the system will create a free-standing project. The project will include your container settings, IDE settings etc, so you can just open it your IDE to run and debug.

 

Guided Demo

Demonstrations of API Logic Server often follow this script, provided as take-away notes.

Guided Demo Summary

 

1. Run the automatic Admin App, and Swagger
   
   

2. Explore the Admin App (no html, js): ui/admin/admin.yaml
   
   

3. Explore the API

   • Automatic API: api/expose_api_models.py
     • database/models.py - from schema
   • Custom Endpoint: api/customize_api.py - see add_order()
     
     

4. Explore logic/declare_logic.py

   • Executable Design - declarative
   • Breakpoint here
     
     

5. Run Custom APIs and Logic Execution / Debugging

   • In swagger: POST ServicesEndPoint/add_order > Try it out
   • At the breakpoint, observe the
     • Debugger State -- row attributes, etc
     • Logic Log -- line for each rule fire, showing row, with indents for chaining

 

 

Key Technology Concepts

Key Technology Concepts

Select a skill of interest, and
Click the link to see sample code

 

Tech Area	Skill	App_Fiddle Example	APILogicProject Logic Example	Notes
Flask	Setup	flask_basic.py	api_logic_server_run.py
	Events		ui/admin/admin_loader.py
API	Create End Point	api/end_points.py	api/customize_api.py	see def order():
	Call endpoint		test/.../place_order.py
Config	Config	config.py
	Env variables		config.py	os.getenv(...)
SQLAlchemy	Data Model Classes	database/models.py
	Read / Write	api/end_points.py	api/customize_api.py	see def order():
	Multiple Databases		database/bind_databases.py
	Events		security/system/security_manager.py
Logic	Business Rules	n/a	logic/declare_logic.py	Unique to API Logic Server
Security	Multi-tenant	n/a	security/declare_security.py
Behave	Testing		test/.../place_order.py
Alembic	Schema Changes		database/alembic/readme.md
Docker	Dev Env		.devcontainer/devcontainer.json	See also "For_VS_Code.dockerFile"
	Containerize Project		devops/docker/build-container.dockerfile