{"id":27926024,"url":"https://github.com/anselm94/sapbtp-flask-bookstore-template","last_synced_at":"2026-04-30T13:33:54.236Z","repository":{"id":291570865,"uuid":"977944780","full_name":"anselm94/sapbtp-flask-bookstore-template","owner":"anselm94","description":"A reference sample bookstore Flask API server to deploy in BTP with XSUAA (authn \u0026 authz), HANA SQLAlchemy, HDI deployment, logging with MTA based development","archived":false,"fork":false,"pushed_at":"2025-06-01T07:23:02.000Z","size":323,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-30T13:33:44.578Z","etag":null,"topics":["flask","hana","mta","python","sap","ui5","xsuaa"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anselm94.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-05T08:20:19.000Z","updated_at":"2025-06-01T07:23:05.000Z","dependencies_parsed_at":"2025-05-05T12:53:13.216Z","dependency_job_id":null,"html_url":"https://github.com/anselm94/sapbtp-flask-bookstore-template","commit_stats":null,"previous_names":["anselm94/sapbtp-flask-bookstore","anselm94/sapbtp-flask-bookstore-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/anselm94/sapbtp-flask-bookstore-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselm94%2Fsapbtp-flask-bookstore-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselm94%2Fsapbtp-flask-bookstore-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselm94%2Fsapbtp-flask-bookstore-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselm94%2Fsapbtp-flask-bookstore-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anselm94","download_url":"https://codeload.github.com/anselm94/sapbtp-flask-bookstore-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselm94%2Fsapbtp-flask-bookstore-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32466333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask","hana","mta","python","sap","ui5","xsuaa"],"created_at":"2025-05-07T00:51:01.043Z","updated_at":"2026-04-30T13:33:54.230Z","avatar_url":"https://github.com/anselm94.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 **SAP BTP Flask Starter App**\n\n### **Build Production-Ready Flask Apps on SAP BTP with Ease!**\n\n---\n\n## 🌟 **Introduction**\n\nWelcome to the **SAP BTP Flask Starter App**! This repository is your one-stop solution for building and deploying production-grade Flask applications on SAP Business Technology Platform (BTP). With built-in support for **XSUAA authentication \u0026 authorization**, **HANA database integration**, and **MTA deployment**, this project is designed to help developers—both beginners and experts—hit the ground running. 🎉\n\n---\n\n## ✨ **Features**\n\n- **🧑‍💻 Friendly Developer-Experience (DX)**\n  Developer Experience was the top goal of this project. Use **Basic Auth** for _local_ development while using **XSUAA Auth** for _production_. Similarly, use **SQLite** for _local_ development while using **SAP HANA** for _production_.\n\n- **🔒 XSUAA Authentication \u0026 Authorization**  \n  Secure your app with SAP's XSUAA service for seamless authentication and role-based access control.\n\n- **🛠️ HANA Integration**  \n  Leverage SAP HANA for robust database management with SQLAlchemy and [`@sap/cds-dk`](https://www.npmjs.com/package/@sap/cds-dk) for HDI artifact generation.\n\n- **📦 MTA Deployment**  \n  Effortlessly deploy your app using the [Multi-Target Application (MTA) framework](https://help.sap.com/docs/btp/sap-business-technology-platform/multitarget-applications-in-cloud-foundry-environment).\n\n- **⚡ Local \u0026 Production Configurations**  \n  Automatically adapt to local or production environments with minimal setup by setting `FLASK_ENV` environment variable\n\n- **📋 CF Logging**  \n  Integrated Cloud Foundry logging for better observability using [`cf-python-logging-support`](https://github.com/SAP/cf-python-logging-support)\n\n- **🚀 Gunicorn for Production**  \n  Run your app with the high-performance [Gunicorn WSGI server](https://gunicorn.org/) in production.\n\n- **🩺 Health Check Endpoint**  \n  Monitor app and database liveliness via the `/health` endpoint.\n\n---\n\n## 🤔 **Why Use This Repository?**\n\n- **Time-Saving**: Pre-configured for SAP BTP, so you can focus on building features.\n- **Best Practices**: Implements SAP standards for BTP apps.\n- **Scalable**: Designed to grow with your application needs.\n- **Beginner-Friendly**: Easy-to-follow setup and documentation.\n\n---\n\n## 🏁 **How to Use This Repository**\n\nThis repository is a **template repository**. To start your own project based on this starter app:\n\n1. Click the green **\"Use this template\"** button at the top of the [GitHub repository page](https://github.com/anselm94/sapbtp-flask-bookstore-template).\n   !['Use this template' button in Github repository](./docs/step-usethistemplate.png)\n2. Choose **\"Create a new repository\"** and fill in your desired repository name and settings.\n3. Follow the [Getting Started](#getting-started) instructions below to set up your environment.\n\n\u003e [!TIP]\n\u003e\n\u003e Using the template ensures you start with a clean commit history and can customize your project independently.\n\n---\n\n## 🛠️ **Getting Started**\n\n### **Pre-requisites**\n\n1. Install [NodeJS](https://nodejs.org/en/download).\n2. Install [`poetry`](https://python-poetry.org/docs/#installation) for dependency management.\n3. Install [CF CLI](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html).\n\n### **Setup**\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone https://github.com/anselm94/sapbtp-flask-bookstore.git\n   cd sapbtp-flask-bookstore\n   ```\n\n2. **Create and Activate a Virtual Environment**\n\n   ```bash\n   python -m venv .venv\n   source .venv/bin/activate\n   ```\n\n3. **Install [`cds-dk`](https://cap.cloud.sap/docs/tools/cds-cli) \u0026 [`mbt`](https://sap.github.io/cloud-mta-build-tool/) tooling**\n\n   ```bash\n   npm install\n   ```\n\n4. **Deploy DB artefacts**\n\n   Deploy DB artefacts to local SQLite DB file.\n\n   ```bash\n   # in root project dir\n   npm run deploy:sqlite\n   ```\n\n   \u003e [!NOTE]\n   \u003e\n   \u003e You must repeat the above command everytime for every CDS file change in [`db/`](db/) folder\n\n5. **Install Poetry Dependencies**\n\n   ```bash\n   cd srv \u0026\u0026 poetry install\n   ```\n\n6. **Start the Local Server**\n\n   The local server starts with SQLite as DB and Basic User (username: `me` \u0026 password: `me`)\n\n   ```bash\n   # in `srv` folder\n   python -m flask run\n   ```\n\n7. **Test the API**\n\n   - Health Check\n\n   ```http\n   GET http://127.0.0.1:5000/health\n   ```\n\n   - Get `books` API\n\n   ```http\n   GET http://127.0.0.1:5000/api/v1/books\n\n   Authorization: Basic me:me\n   ```\n\n8. **Run Tests**\n\n   ```bash\n   # in `srv` folder\n   python -m pytest\n   ```\n\n9. **See Coverage Reports**\n\n   - Open generated HTML coverage reports in [`srv/htmlcov/`](srv/htmlcov/) folder\n\n### **Deploy to Cloud Foundry**\n\n1. **Build the MTA Project**\n\n   ```bash\n   # in project root dir\n   mbt build\n   ```\n\n2. **Push the Artefact**\n\n   ```bash\n   # in project root dir\n   cf deploy mta_archives/sapbtp-flask-bookstore_1.0.0.mtar\n   ```\n\n3. **Test the API**\n\n   Check the BTP Cockpit for the URL.\n\n   - Health Check\n\n   ```http\n   GET https://\u003cBTP_APP_DEPLOYMENT_URL\u003e/health\n   ```\n\n   - Get `books` API\n\n   Get an `oauth2_token` before running the following check\n\n   ```http\n   GET http://\u003cBTP_APP_DEPLOYMENT_URL\u003e/api/v1/books\n\n   Authorization: Bearer \u003coauth2_token\u003e\n   ```\n\n\u003e [!TIP]\n\u003e\n\u003e In order to replicate the `PRODUCTION` in the local by connecting to HANA DB and use oAuth2 authentication flow, you can replicate the `VCAP_SERVICES` in the local and set `FLASK_ENV=PRODUCTION`. See [`config.py`](./srv/config.py) for more info\n\u003e\n\u003e 1. Copy [`.env.example`](./.env.example) to `.env`\n\u003e 2. Run the setup script to populate `VCAP_SERVICES`\n\u003e    ```bash\n\u003e    sh setup-env.sh\n\u003e    ```\n\u003e 3. Run the app locally\n\u003e    ```bash\n\u003e    cd srv\n\u003e    FLASK_ENV=PRODUCTION python -m flask run\n\u003e    ```\n\u003e 4. Test the API with oAuth2 credentials\n\n---\n\n## 📂 **Project Structure**\n\n```plaintext\nsapbtp-flask-bookstore/\n├── db/                               # CDS schema and data files\n│   ├── schema.cds                    # Core Data Services (CDS) schema definition\n│   ├── data/                         # Sample data for the database\n├── gen/                              # Generated HANA artifacts\n├── srv/                              # Flask application source code\n│   ├── app.py                        # Entry point for the Flask application\n│   ├── config.py                     # Configuration management for different environments\n│   ├── app/                          # Application modules\n│   │   ├── database.py               # Database connection and setup logic\n│   │   ├── models.py                 # ORM models for database tables\n│   │   ├── routes/                   # API route definitions\n│   │   │   ├── __init__.py           # Route initialization\n│   │   ├── services/                 # Business logic and service layer\n│   │   │   ├── books_service.py      # Service logic for book-related operations\n│   │   ├── utils/                    # Utility functions for authentication and error handling\n│   │   │    ├── auth_utils.py        # Authentication helper functions\n|   │   │    ├── heathcheck_utils.py  # Healthcheck helper functions\n│   ├── tests/                        # Unit Tests\n├── mta.yaml                          # MTA deployment descriptor\n├── setup-env.sh                      # Script to configure local environment\n└── README.md                         # Project documentation\n```\n\n---\n\n## 🔍 **How It Works**\n\n1. **Authentication \u0026 Authorization**\n\n   - Use `@login_required` for any route, which needs **authentication**\n   - Use `@roles_required([\"role-1\", \"role-2\"])` for any route, which needs necessary scope **authorization**\n\n   **Local Development**\n\n   - Uses _Basic Auth_ for quick and easy development in the local - See [`srv/config.py`](srv/config.py), [`srv/app/routes/__init__.py`](srv/app/routes/__init__.py) \u0026 [`srv/app/utils/auth_utils.py`](srv/app/utils/auth_utils.py)\n   - Validate Role-based access control as defined for mock users in [`srv/config.py`](srv/config.py)\n   - Configure default mock users and roles in [`srv/config.py`](srv/config.py)\n\n   **Production**\n\n   - Uses _SAP XSUAA_ for OAuth2-based authentication \u0026 authorization - See [`srv/config.py`](srv/config.py), [`srv/app/routes/__init__.py`](srv/app/routes/__init__.py) \u0026 [`srv/app/utils/auth_utils.py`](srv/app/utils/auth_utils.py)\n   - Role-based access control is defined in [`xs-security.json`](./xs-security.json).\n\n2. **Database Integration**\n\n   - All DB artefacts are modelled in [SAP CDS - Conceptual Definition Language](https://cap.cloud.sap/docs/cds/cdl) format - See [`db/schema.cds`](db/schema.cds)\n   - Uses [`@sap/cds-dk` CLI](https://cap.cloud.sap/docs/tools/cds-cli) for compiling CDS CDL to target DB DDL format and deploy them at ease.\n   - [SQLAlchemy](https://flask-sqlalchemy.readthedocs.io/en/stable/) is used for ORM mapping in the Flask app ([`srv/app/models.py`](./srv/app/models.py)) using 'SQLite dialect' or '[SAP HANA dialect](https://github.com/SAP/sqlalchemy-hana)'.\n   - Easily load default CSV data configurations - see [`db/data/`](db/data/)\n   - CDS models ([`db/schema.cds`](./db/schema.cds)) are converted to HANA HDI artifacts using [`@sap/cds-dk`](https://www.npmjs.com/package/@sap/cds-dk).\n\n   **Local Development**\n\n   - Run `npm run deploy:sqlite` in the root project dir to deploy the latest CDS changes in [`db/`](db/) folder to the local SQLite DB files.\n\n   **Production**\n\n   - Use [SAP HANA Deployer - `@sap/hdi-deploy`](https://help.sap.com/docs/SAP_HANA_PLATFORM/4505d0bdaf4948449b7f7379d24d0f0d/1b567b05e53c4cb9b130026cb2e7302d.html) for automated HANA artefact migration and deployment\n\n3. **Health Checks**\n\n   - Checks for dependent services' availability for health check endpoint `/health` - see [`srv/app/utils/heathcheck_utils.py`](srv/app/utils/heathcheck_utils.py)\n\n4. **Automated Tests**\n\n   - Uses [`pytest`](https://docs.pytest.org/en/stable/) framework with [`pytest-flask`](https://pytest-flask.readthedocs.io/en/latest/) for automated tests.\n   - Uses [`pytest-cov`](https://pytest-cov.readthedocs.io/en/latest/readme.html) for coverage reporting\n\n5. **Deployment**\n\n   - MTA framework bundles the app, database, and services for deployment.\n   - [`cf deploy`](https://docs.cloudfoundry.org/devguide/deploy-apps.html) handles the deployment to SAP BTP.\n\n---\n\n## 🧑‍💻 **Development Workflow**\n\n- **Debugging**: Use VS Code's built-in debugger with the provided `launch.json`.\n- **Extending**:\n  - Add new routes in [`srv/app/routes/`](./srv/app/routes/__init__.py)\n  - Add new services in [`srv/app/services/`](./srv/app/services/).\n  - Add new models in [`db/schema.cds`](./db/schema.cds) and [`srv/app/models.py`](./srv/app/models.py)\n\n---\n\n## 📜 **License**\n\nThis project is licensed under the [MIT License](./LICENSE).\n\n---\n\n## 🙌 **Acknowledgments**\n\nSpecial thanks to the SAP BTP community and contributors for their support and inspiration!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanselm94%2Fsapbtp-flask-bookstore-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanselm94%2Fsapbtp-flask-bookstore-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanselm94%2Fsapbtp-flask-bookstore-template/lists"}