Create JSON:API and Web App from database, with LogicBank -- 40X more concise, Python for extensibility.
Project description
API Logic Server
TL;DR - Creates Customizable, Executable Database Projects
The ApiLogicServer create-and-run
command creates a executable, customizable project that provides:
-
Admin App (running here on PythonAnywhere) - multi-page, multi-table, automatic joins
-
API, with Swagger - endpoint for each table, with filtering, pagination, related data
-
Business Logic, using rules for multi-table derivations and constraints, extensible with Python
- Declare rules as in a spreadsheet - 40X more concise than code
- Unique to API Logic Server :trophy:
Here's How: Single Command Project Creation
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 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=
Your system is running - explore the data and api at localhost:5656, or on this deployed system.
VSCode and PyCharm users can execute within their IDE with these steps.
In addition to Docker, you can install locally; if Python 3.7+ is installed, it's typically:
python3 -m venv venv # may require python -m venv venv
source venv/bin/activate # windows venv\Scripts\activate
apt install unixodbc-dev # Linux only
pip install ApiLogicServer # you may need to use pip3, or restart your terminal session
ApiLogicServer create # create, or create-and-run; defaults provided
Process Overview - Project Creation from Database Introspection
Project creation is based on database schema introspection as shown below. Click for a video tutorial, showing complete project creation, execution, customization and debugging.
After you've explored the tutorial (created from this database), try out our dockerized test databases, and then try your own database.
Already installed? Upgrade to the latest (5.02.16):
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 Application Integration |
SAFRS |
3. Transactional Logic | Spreadsheet-like Rules 40X more concise - compare legacy code |
Unique backend automation ... nearly half the system |
Logic Bank |
4. Customizable Project | Custom Data Model, Endpoints, Logic Use Python and yourIDE |
Customize and run Re-creation not required |
VS Code PyCharm ... |
5. Model Creation | Classes for Python-friendly ORM | Custom Data Access Used by API |
SQLAlchemy |
6. Behave Test Framework | Test Suite Automation Behave Logic Report Drive Automation with Agile |
Optimize Automation to get it fast Agile Collaboration to get it right |
Logic Tutorial |
The following tutorial is a good way to explore API Logic Server.
API Logic Server - Sample Tutorial
After completing the create
step, 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:
- Click Run and Debug
- Note: these steps are highlighted in the diagram below
- Select the
ApiLogicServer
Launch Configuration - 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
- 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
- Navigate to
- (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:
- Click View > Command to open the Command Palette
- Enter command:
Simple Browser: Show
- Specify the URL:
http://localhost:5656/api
- Enter command:
- Explore the swagger
- Note: you can drag windows to arrange your viewing area
- (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:
- Open Explorer > ui/admin/admin.yaml
- Find and alter the string
- label: 'Placed Order List*'
(e.g, make it plural) - Click Save
- Find and alter the string
- Launch the app: http://localhost:5656
- Load the updated configuration: click Configuration > Reset
- 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:
- Open Explorer > api/customize_api.py:
- Set the breakpoint as shown
- Use the swagger to access the
ServicesEndPoint > add_order
, and- Try it out, then
- execute
- Your breakpoint will be hit
- You can examine the variables, step, etc.
- Click Continue on the floating debug menu (upper right in screen shot below)
Logic
API and UI automation are impressive answers to familiar challenges. Logic automation is a unique answer to a significant and unaddressed problem:
For transaction systems, backend constraint and derivation logic is often nearly half the system. This is not addressed by conventional approaches of "your code goes here".
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:
- Open Explorer > logic/declare_logic.py:
- Observe the 5 rules highlighted in the diagram below. These are built with code completion.
- Set a breakpoint as shown
- This event illustrates that logic is mainly rules, extensible with standard Python code
- Using swagger, re-execute the
add_order
endpoint - When you hit the breakpoint, expand
row
VARIABLES list (top left)
Test
You can test using standard api and ui test tools. We recommend exploring the Behave framework. This can be used as part of an overall agil approach as described in the Logic Tutorial.
TL;DR - features and test scripts are predefined in the sample; to run them (with the server running):
- Run Launch Configuration
Run Behave Logic
- Run Launch Configuration
Behave Logic Report
- Open
test/api_logic_server_behave/reports/Behave Logic Report.md
The sample Scenarios below were chosen to illustrate the basic patterns of using rules. Open the disclosure box ("Tests - and their logic...") to see the implementation and notes.
For more information, see Working with Behave.
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
Next Steps
Explore the Logic Tutorial.
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
- Windows - Powershell must be used (due to the
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), orC:\Users\val\dev\servers
(windows)
- You could also provide a specific folder, e.g.,
/localhost
is 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
apt install unixodbc-dev # Linux only
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 the Quick Start - open Install-Guide > Installation Details > pythonanywhere.
Here is the sample app, running on PythonAnywhere.
Quick Start
Once installed, use the Quick Start to create and load the sample project.
Installation Notes
Alert - Project fails to start
Recent updates to included libs have broken previous versions of API Logic Server. This is fixed in a new version (5.00.06), and is strongly recommended. You can also repair broken installations as described in Troubleshooting.
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 runningpython3 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
replaceslogic_bank.py
api/customize_api.py
replacesexpose_services.py
database/customize_models.py
replacesmodels_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:
- How Automation Activates Agile - providing working software rapidly drives agile collaboration to define systems that meet actual needs, reducing requirements risk
- How to create application systems in moments
- Stop coding database backends…Declare them with one command.
- Instant Database Backends
- Extensible Rules - defining new rule types, using Python
- Declarative - exploring multi-statement declarative technology
- Automate Business Logic With Logic Bank - general introduction, discussions of extensibility, manageability and scalability
- Agile Design Automation With Logic Bank - focuses on automation, design flexibility and agile iterations
- Instant Web Apps
Change Log
06/05/2022 - 05.02.17: Model customizations simplified, better logging
05/30/2022 - 05.02.16: Python 3.10, Dockerfile include, start info
05/25/2022 - 05.02.12: Verified for Python 3.10, improved support for configuring venv
05/04/2022 - 05.02.03: alembic for database migrations, admin-merge.yaml
04/24/2022 - 05.01.01: copy_children, with support for nesting (children and grandchildren, etc.)
03/27/2022 - 05.00.06: Introducing Behave test framework, LogicBank bugfix
02/18/2022 - 04.02.03: SqlServer fixes, rebuild creates '-created' versions for data model repair
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
Built Distribution
Hashes for ApiLogicServer-5.2.17-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 12c573c834b559d8c3c418a6f0efe78b1eb975b249ba9d1c595b9ab4592e0691 |
|
MD5 | 8a628d54427dac1c3acfca65bc97b4d1 |
|
BLAKE2b-256 | 664da023cac3c3d7575732d98895ff5939febfb9cd5471b790014970880735fe |