Skip to main content

Create JSON:API and Web App from database, with LogicBank -- 40X more concise, Python for extensibility.

Project description

Downloads Latest Version Supported Python versions

API Logic Server

TL;DR - creates customizable, model-driven database systems - instantly - from your database

The ApiLogicServer create-and-run command creates a executable, customizable project providing:

  1. Automatic Admin App (running here on PythonAnywhere)

    • For instant collaboration and Back Office data maintenance
    • Rich functionality: multi-page, multi-table, automatic joins
    • Explore this Admin App, and how to customize it
  2. API, with Swagger

    • For custom app dev, integration
    • Rich functionality: endpoint for each table, with filtering, pagination, related data
    • Customizable: add your own endpoints
  3. Business Logic, for backend processing

    • Spreadsheet-like rules for multi-table derivations and constraints
    • Extensible with Python events for email, messages, etc
    • Explore how logic can meaningfully improve conciseness and quality

To create the sample API and app project in a minute or two -- start Docker, and execute the following commands (Windows, use Powershell):

cd ~/Desktop                       # directory of API Logic Server projects on local host

# Start (install if required) the API Logic Server docker container
docker run -it --name api_logic_server --rm -p 5656:5656 -p 5002:5002 -v ${PWD}:/localhost apilogicserver/api_logic_server

ApiLogicServer create-and-run --project_name=/localhost/ApiLogicProject --db_url=  # Working Software, Now

Your system is running - explore the data and api locally, or on this deployed systems.

VSCode and PyCharm users can execute within their IDE with these steps.

In addition to Docker, you can install locally, or on the cloud.

You can picture the process as shown in the diagram below; click it for a video tutorial, showing complete project creation, execution, customization and debugging.

Using VS Code

After you've explored the tutorial, try out our dockerized test databases, and then try your own database.

Already installed? Upgrade to the latest (4.01.08): docker pull apilogicserver/api_logic_server (you may need to rebuild your container).

Feature Summary

Feature Providing Why it Matters Learn More
1. Admin App Instant multi-page, multi-table app Engage Business Users
Back-office Admin
safrs-react-admin
2. JSON:API and Swagger Endpoint for each table, with...
Filtering, pagination, related data
Unblock custom App Dev SAFRS
3. Transactional Logic Spreadsheet-like Rules - 40X more concise
Compare Check Credit with legacy code
Strategic Business Agility Logic Bank
4. Customizable Project Custom Data Model, Endpoints, Logic Customize and run
Re-creation not required
VS Code
PyCharm ...
5. Model Creation Python-friendly ORM Custom Data Access
Used by API
SQLAlchemy

The following tutorial is a good way to explore API Logic Server.

  

API Logic Server - Sample Tutorial

After completing the Create step below, you can view the readme in the created ApiLogicProject. It contains the sample tutorial, created from this database.

In this tutorial, we will explore:

  • run - we will first run the Admin App and the JSON:API

  • customize - we will then explore some customizations already done for the API and logic, and how to debug them

This tutorial presumes you are running in an IDE - VS Code or PyCharm. Projects are pre-configured for VS Code with .devcontainer and launch configurations, so these instructions are oriented around VS Code. You will need to configure container and launch configurations for PyCharm - see here for more information.

The diagram above summarizes the create / run / customize process. You can watch the tutorial in this video.

   

Run

Created ApiLogicProjects are instantly executable. Let's explore the Admin App and the API.

Admin App: Multi-Page, Multi-Table, Automatic Joins

To run the Admin App, follow these steps:

  1. Click Run and Debug
    • Note: these steps are highlighted in the diagram below
  2. Select the ApiLogicServer Launch Configuration
  3. Press the green run button to start the server
    • If you are running Docker / VS Code, and VS Code will suggest opening a Browser (the preview browser is shown below). Do so, and you should see the Home screen in your Browser.
    • Otherwise, you can:
      • Open a browser at localhost:5656, or
      • Click View > Command Palette, select Simple Browser, and specify the same url
        • Note: be aware that we have seen some issue where the simple browser fails to start; just use your normal browser
  4. Explore the app: multi-page, multi-table, automatic joins
    • Navigate to Customer
      • Depending on your screen size, you may need to hit the "hamburger menu" (top left) to see the left menu
    • Click the Customer row to see Customer Details
    • Observe the Placed Order List tab at the bottom
    • Click the first Order row
    • Click the Order Detail List tab at the bottom
    • Click the first Product Id to see its detail information
  5. (Close the app (browser), but leave the server running)

  

Key Take-away: instant multi-page / multi-table admin apps, suitable for back office, and instant agile collaboration.

 

JSON:API - Related Data, Filtering, Sorting, Pagination, Swagger

Your API is instantly ready to support ui and integration development, available in swagger, as shown below. JSON:APIs are interesting because they are client configurable to reduce network traffic and minimize organizational dependencies.

The creation process builds not only the API, but swagger so you can explore it. The Admin App Home page provides a link to the swagger, but it doesn't work in VS Code's simple browser. So, we'll launch a new Simple Browser, like this:

  1. Click View > Command to open the Command Palette
    • Enter command: Simple Browser: Show
    • Specify the URL: http://localhost:5656/api
  2. Explore the swagger
    • Note: you can drag windows to arrange your viewing area
  3. (Leave the swagger and server running)
   

Key Take-away: instant rich APIs, with filtering, sorting, pagination and swagger. Custom App Dev is unblocked.

   

Customize and Debug

That's quite a good start on a project. But we've all seen generators that get close, but fail because the results cannot be extended, debugged, or managed with tools such as git and diff.

Let's examine how API Logic Server projects can be customized for both APIs and logic. We'll first have a quick look at the created project structure, then some typical customizations.

The API and admin app you just reviewed above were not customized - they were created completely from the database structure. For the sample project, we've injected some API and logic customizations, so you can explore them in this tutorial, as described below.

Project Structure

Use VS Code's Project Explorer to see the project structure:

Directory Usage Key Customization File Typical Customization
api JSON:API api/customize_api.py Add new end points / services
database SQLAlchemy Data Model Classes database/customize_models.py Add derived attributes, and relationships missing in the schema
logic Transactional Logic logic/declare_logic.py Declare multi-table derivations, constraints, and events such as send mail / messages
ui Admin App ui/admin/admin.yaml Control field display, ordering, etc.

Let's now explore some examples.

Admin App Customization

There is no code for the Admin app - it's behavior is declared in the admin.yaml model file. Alter this file to control labels, hide fields, change display order, etc:

  1. Open Explorer > ui/admin/admin.yaml
    • Find and alter the string - label: 'Placed Order List*' (e.g, make it plural)
    • Click Save
  2. Launch the app: http://localhost:5656
  3. Load the updated configuration: click Configuration > Reset
  4. Revisit Customer > Order to observe the new label

   

Key Take-away: you can alter labels, which fields are displayed and their order, etc -- via a simple model. No need to learn a new framework, or deal with low-level code or html.

   

API Customization

While a standards-based API is a great start, sometimes you need custom endpoints tailored exactly to your business requirement. You can create these as shown below, where we create an additional endpoint for add_order.

To review the implementation:

  1. Open Explorer > api/customize_api.py:
  2. Set the breakpoint as shown
  3. Use the swagger to access the ServicesEndPoint > add_order, and
    1. Try it out, then
    2. execute
  4. Your breakpoint will be hit
    1. You can examine the variables, step, etc.
  5. Click Continue on the floating debug menu (upper right in screen shot below)

Logic

We've all seen excellent technology that can create great User Interfaces. But for transactional systems, their approach to logic is basically "your code goes here".

That's a problem - for transaction systems, the backend constraint and derivation logic is often nearly half the system.

The logic portion of API Logic server is a declarative approach - you declare spreadsheet-like rules for multi-table constraints and derivations. The 5 rules shown below represent the same logic as 200 lines of Python - a remarkable 40X.

Since they automate all the re-use and dependency management, rules are 40X more concise than code.

Logic consists of rules and conventional Python code. Explore it like this:

  1. Open Explorer > logic/declare_logic.py:
    • Observe the 5 rules highlighted in the diagram below. These are built with code completion.
  2. Set a breakpoint as shown
    • This event illustrates that logic is mainly rules, extensible with standard Python code
  3. Using swagger, re-execute the add_order endpoint
  4. When you hit the breakpoint, expand row VARIABLES list (top left)

   

Wrap up

Let's recap what you've seen:

  • ApiLogicProject Creation and Execution - a database API and an Admin App - created automatically from a database, in moments instead of weeks or months

  • Customizable - the UI, API and Logic - using Visual Studio code, for both editing and debugging

Docker cleanup

VS Code leaves the container and image definitions intact, so you can quickly resume your session. You may wish to delete this. it will look something like vsc-ApiLogicProject....

   

Project Operations

Please see the wiki for details on project operations.

Architectural Overview

Please see Architecture.

Command Language Details

Click to see Docker run argument descriptions, and how to inspect Docker environment

Install - docker run

Once you've installed Docker itself, the docker run command above installs the ApiLogicServer docker (if it's not already there), and starts it, opening a terminal window on the Docker container. Notes:

  • the v ${PWD}:/localhost argument is what enables the ApiLogicServer to create / access the project on your local host
    • Windows - Powershell must be used (due to the $(PWD) syntax)
    • if you use Command Prompt, specify the local directory completely

The arguments mean:

  • -it - launch a terminal window for the Docker container
  • --name api_logic_server - the name of the image on your local host
  • -rm - remove the container once it stops (your project files are not lost - they are on your local host)
  • -p 5656:5656 - maps local (host) part to Docker port
  • -v ${PWD}:/localhost - maps a local directory to a mount name for Docker. This is where a directory will be created for your new project.
    • ${PWD} is your current folder.
      • You could also provide a specific folder, e.g., ~/dev/servers (Unix), or C:\Users\val\dev\servers (windows)
    • /localhostis the mounted volume reference from inside the Docker container
  • apilogicserver/api_logic_server - the name of the image to pull from Docker Hub.
    • This will fetch the image first time, and will run it locally on subsequent runs
    • The image is not automatically refreshed -- install ApiLogicServer updates as described below

You may also wish to add a parameter for networking:

  • --net my-network - attaches to my-network

On your Docker container, you can inspect your environment:

python py.py

Open a new terminal window on your local host, and find your docker IP address:

docker inspect api_logic_server  # you will find the ip, e.g., 172.17.0.2

Internals - How It Works

Please see Architecture - How It Works.

Installation

As of release 3.00.00, you can install using Docker (recommended), standard pip install, or PytonAnywhere.

Installation Options

Docker Installation

Docker installation enables you to bypass sometimes-tricky Python installs by using Docker.

Docker support provides not only ApiLogicServer, but a Python environment you can use with your IDE. It is described above.

See the link above for more information on install and execution.

Local Installation

Caution: Python install is rather more than running an installer. Use this page to Verify / Install Python.

Then, install the ApiLogicServer CLI in the usual manner:

python3 -m venv venv       # may require python -m venv venv
source venv/bin/activate   # windows venv\Scripts\activate
pip install ApiLogicServer # you may need to use pip3, or restart your terminal session

Cloud Install - Pythonanwhere

API Logic Server runs well on pythonanywhere. See these instructions.

Here is the sample on PythonAnywhere.

Quick Start

Once installed, use the Quick Start to create and load the sample project.

Installation Notes

Heads up - Certificate Issues

We sometimes see Python / Flask AppBuilder Certificate issues - see Troubleshooting.

Default Python version

In some cases, your computer may have multiple Python versions, such as python3. ApiLogicServer run relies on the default Python being 3.8 or higher. You can resolve this by:

  • making python3 the default Python, or
  • using ApiLogicServer create, and running python3 api_logic_server_run.py

Project Information

Tutorials

There are a number of facilities that will quickly enable you to get familiar with API Logic Server:

  • Tutorial walks you through the steps of creating a server
  • Video shows the steps of creating a server

Status

We have tested several databases - see status here.

We are tracking issues in git.

We have introduced several renames to clarify operation. These do not affect existing projects. However, we've not updated all the docs to reflect these changes:

  • logic/declare_logic.py replaces logic_bank.py
  • api/customize_api.py replaces expose_services.py
  • database/customize_models.py replaces models_ext.py

Acknowledgements

Many thanks to

  • Thomas Pollet, for SAFRS, SAFRS-react-admin, and invaluable design partnership
  • Marelab, for react-admin
  • Armin Ronacher, for Flask
  • Mike Bayer, for SQLAlchemy
  • Alex Grönholm, for Sqlacodegen
  • Meera Datey, for React Admin prototyping
  • Denny McKinney, for Tutorial review
  • Achim Götz, for design collaboration and testing
  • Max Tardiveau, for testing and help with Docker
  • Michael Holleran, for design collaboration and testing
  • Nishanth Shyamsundar, for review and testing
  • Thomas Peters, for review and testing
  • Daniel Gaspar, for Flask AppBuilder
  • Gloria Huber and Denny McKinney, for doc review

Articles

There are a few articles that provide some orientation to Logic Bank and Flask App Builder. These technologies are automatically created when you use ApiLogicServer:

Change Log

01/18/2022 - 04.01.01: fix startup failure on created app (windows pip-install version only)

01/14/2022 - 04.01.00: add info_disp/show, attribute info, performance, date fix

12/26/2021 - 04.00.05: Introducing the Admin app, with Readme Tutorial

11/13/2021 - 03.50.00: rebuild-from-database/model, improved relationship support

11/04/2021 - 03.40.01: Per macOS Monterey, default ports to 5001, 5002

10/18/2021 - 03.20.11: Readme Tutorial for IDE users

10/16/2021 - 03.20.07: dev-network no longer required (see Releases)

10/03/2021 - 03.10.17: default db_url

10/02/2021 - 03.01.16: bugfix improper run arg for VSCode launch configuration

09/29/2021 - 03.01.15: run (now just runs without create), added create-and-run

09/25/2021 - 03.01.10: enable run command for Docker execution, pyodbc, fab create-by-copy

09/15/2021 - 03.00.09: auto-create .devcontainer for vscode, configure network, python & debug

09/10/2021 - 03.00.02: rename logic_bank to declare_logic, improved logging

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ApiLogicServer-4.1.12.tar.gz (6.8 MB view hashes)

Uploaded Source

Built Distribution

ApiLogicServer-4.1.12-py3-none-any.whl (7.1 MB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page