Initial additions

rhedgpeth · rhedgpeth · commit 6e94006c1d1e · 2022-01-05T14:30:05.000-06:00
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "src/client"]
+	path = src/client
+	url = https://github.com/mariadb-developers/places-app-client.git
diff --git a/README.md b/README.md
@@ -0,0 +1,230 @@
+# Places
+
+**Places** is a web application backed by the power of the power, performance, and simplicity of [MariaDB](https://mariadb.com/), allows you to record all of your favorite locations using both structured (relational) and semi-structured (JSON) data!
+
+<p align="center" spacing="10">
+    <kbd>
+        <img src="media/map.png" />
+    </kbd>
+</p>
+
+This application is made of two parts:
+
+* Client
+    - web UI that communicates with REST endpoints available through an API app (see below).
+    - is a React.js project located in the [client](src/client) folder.
+* API
+    - uses the [MariaDB Python Connector](https://github.com/mariadb-corporation/mariadb-connector-python) to connect to MariaDB.
+    - is a Python project located int the [api](src/api) folder.
+
+This README will walk you through the steps for getting the `Places` web application up and running using MariaDB.
+
+# Table of Contents
+1. [Requirements](#requirements)
+2. [Getting started with MariaDB and JSON](#mariadb)
+2. [Get the code](#code)
+4. [Configure, build and run the apps](#app)
+    1. [Configure](#configure-api-app)
+    2. [Create and activate a Python virtual environment](#activate-virtual-env)
+    3. [Install Python packages](#install-python-packages)
+    4. [Build and run the Python API app](#build-run-api)
+    5. [Build and run the Client app](#build-run-client)
+5. [JSON Data Models](#data-models)
+6. [Support and contribution](#support-contribution)
+7. [License](#license)
+
+## Requirements <a name="requirements"></a>
+
+This sample application requires the following to be installed/enabled on your machine:
+
+* [Python (v. 3+)](https://www.python.org/downloads/)
+* [MariaDB Connector/C (v. 3.1.5+)](https://mariadb.com/products/skysql/docs/clients/mariadb-connector-c-for-skysql-services/) (used by Connector/Python)
+* [Node.js (v. 12+)](https://nodejs.org/docs/latest-v12.x/api/index.html) (for the Client/UI app)
+* [NPM (v. 6+)](https://docs.npmjs.com/) (for the Client/UI app)
+* [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) (optional), used to connect to MariaDB database instances.
+
+## 1.) Getting Started with MariaDB and JSON <a name="mariadb"></a>
+
+Set up a MariaDB database, loaded with the data this sample needs, using the [MariaDB JSON Quickstart](https://github.com/mariadb-developers/mariadb-json-quickstart), before continuing to the next step.
+
+## 2.) Get the code <a name="code"></a>
+
+First, use [git](git-scm.org) (through CLI or a client) to retrieve the code using `git clone`:
+Ts
+```
+$ git clone https://github.com/mariadb-developers/places-app-python.git
+```
+
+Next, because this repo uses a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), you will need to pull the [client application](https://github.com/mariadb-developers/todo-app-client) using:
+
+```bash
+$ git submodule update --init --recursive
+```
+
+## 3.) Configure, Build and Run the App <a name="app"></a>
+
+This application is made of two parts:
+
+* Client
+    - web UI that communicates with REST endpoints available through an API app (see below).
+    - is a React.js project located in the [client](src/client) folder.
+* API
+    - uses the [MariaDB Python Connector](https://github.com/mariadb-corporation/mariadb-connector-python) to connect to MariaDB.
+    - is a Python project located int the [api](src/api) folder.
+
+### a.) Configure the app <a name="configure-app"></a>
+
+Configure the MariaDB connection by [adding an .env file to the Node.js project](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/master/documentation/promise-api.md#security-consideration). Add the .env file [here](src/api) (the `api` folder).
+
+Example implementation:
+
+```
+DB_HOST=<host_address>
+DB_PORT=<port_number>
+DB_USER=<username>
+DB_PASS=<password>
+DB_NAME=places
+```
+
+**Configuring db.js**
+
+The environmental variables from `.env` are used within [src/api/tasks.py](src/api/tasks.py) for the MariaDB Python Connector connection configuration settings:
+
+```python
+config = {
+    'host': os.getenv("DB_HOST"),
+    'port': int(os.getenv("DB_PORT")),
+    'user': os.getenv("DB_USER"),
+    'password': os.getenv("DB_PASS"),
+    'database': os.getenv("DB_NAME")
+}
+```
+
+Note: MariaDB SkySQL requires SSL additions to connection. Details coming soon!
+
+### b.) Create and activate a Python virtual environment <a name="activate-virtual-env"></a>
+
+A virtual environment is a directory tree which contains Python executable files and other files which indicate that it is a virtual environment. Basically, it's the backbone for running your Python Flask app.
+
+Creation of [virtual environments](https://docs.python.org/3/library/venv.html?ref=hackernoon.com#venv-def) is done by executing the following command (within [/src/api](src/api)):
+
+```
+$ python3 -m venv venv
+```
+
+**Tip**: Tip: pyvenv is only available in Python 3.4 or later. For older versions please use the [virtualenv](https://virtualenv.pypa.io/en/latest/) tool. 
+
+Before you can start installing or using packages in your virtual environment, you’ll need to activate it. Activating a virtual environment will put the virtual environment-specific python and pip executables into your shell’s PATH.
+
+Activate the virtual environment using the following command (within [/src/api](src/api)):
+
+```bash
+$ . venv/bin/activate activate
+```
+
+### c.) Install Python packages <a name="install-python-packages"></a>
+
+[Flask](https://flask.palletsprojects.com/en/1.1.x/?ref=hackernoon.com) is a micro web framework written in Python. It is classified as a [microframework](https://en.wikipedia.org/wiki/Microframework) because it does not require particular tools or libraries. 
+
+**TL;DR** It's what this app uses for the API.
+
+This app also uses the MariaDB Python Connector to connect to and communicate with MariaDB databases. 
+
+Install the necessary packages by executing the following command (within [/src/api](src/api)):
+
+```bash
+$ pip3 install flask mariadb python-dotenv
+```
+
+### d.) Build and run the [API app](src/api) <a name="build-run-api"></a>
+
+Once you've pulled down the code and have verified that all of the required packages are installed you're ready to run the application! 
+
+From [/src/api](src/api) execute the following CLI command to start the the Python project, which will start the application on https://localhost:8080.
+
+```bash
+$ python3 api.py
+```
+
+### c.) Build and run the [UI (Client) app](src/client) <a name="build-run-client"></a>
+
+Once the API project is running you can now communicate with the exposed endpoints directly (via HTTP requests) or with the application UI, which is contained with the [client](src/client) folder of this repo.
+
+To start the [client](src/client) application follow the instructions [here](https://github.com/mariadb-developers/places-app-client).
+
+## JSON Data Models <a name="data-models"></a>
+
+Below are samples of the data model per Location Type. 
+
+**Attraction (A)**
+```json
+{
+   "category":"Landmark",
+   "lastVisitDate":"11/5/2019"
+}
+```
+
+**Restuarant (R)**
+```json
+{
+   "details":{
+      "foodType":"Pizza",
+      "menu":"www.giodanos.com/menu"
+   },
+   "favorites":[
+      {
+         "description":"Classic Chicago",
+         "price":24.99
+      },
+      {
+         "description":"Salad",
+         "price":9.99
+      }
+   ]
+}
+```
+
+**Sports Venue (S)**
+```json
+{
+   "details":{
+      "yearOpened":1994,
+      "capacity":23500
+   },
+   "events":[
+      {
+         "date":"10/18/2019",
+         "description":"Bulls vs Celtics"
+      },
+      {
+         "date":"10/21/2019",
+         "description":"Bulls vs Lakers"
+      },
+      {
+         "date":"11/5/2019",
+         "description":"Bulls vs Bucks"
+      },
+      {
+         "date":"11/5/2019",
+         "description":"Blackhawks vs Blues"
+      }
+   ]
+}
+```
+
+## Support and Contribution <a name="support-contribution"></a>
+
+Please feel free to submit PR's, issues or requests to this project project directly.
+
+If you have any other questions, comments, or looking for more information on MariaDB please check out:
+
+* [MariaDB Developer Hub](https://mariadb.com/developers)
+* [MariaDB Community Slack](https://r.mariadb.com/join-community-slack)
+
+Or reach out to us diretly via:
+
+* [developers@mariadb.com](mailto:developers@mariadb.com)
+* [MariaDB Twitter](https://twitter.com/mariadb)
+
+## License <a name="license"></a>
+[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=plastic)](https://opensource.org/licenses/MIT)
diff --git a/media/map.png b/media/map.png
diff --git a/src/api/api.py b/src/api/api.py
@@ -0,0 +1,12 @@
+import flask
+from locations import locations
+
+app = flask.Flask(__name__)
+app.config["DEBUG"] = True
+app.register_blueprint(locations)
+
+@app.route("/api/version")
+def version():
+    return "1.0"
+
+app.run(port=8080)
diff --git a/src/api/locations.py b/src/api/locations.py
@@ -0,0 +1,123 @@
+import sys
+import simplejson as json
+import mariadb
+import os
+import flask
+from flask import request
+from flask import Blueprint
+from dotenv import load_dotenv
+
+load_dotenv()
+
+locations = Blueprint('locations', __name__)
+
+config = {
+    'host': os.getenv("DB_HOST"),
+    'port': int(os.getenv("DB_PORT")),
+    'user': os.getenv("DB_USER"),
+    'password': os.getenv("DB_PASS"),
+    'database': os.getenv("DB_NAME")
+}
+
+@locations.route('/api/locations', methods=['GET','POST','PUT','DELETE'])
+def index():
+   conn = mariadb.connect(**config)
+   cur = conn.cursor()
+   json_data = []
+
+   if request.method == 'GET':
+    query = "select id, name, type, longitude, latitude, " \
+            "case when type = 'R' then concat((case when json_length(attr, '$.favorites') " \
+            "is not null then json_length(attr, '$.favorites') else 0 end), ' favorite meals') " \
+            "when type = 'A' then (case when json_value(attr, '$.lastVisitDate') is not null " \
+            "then json_value(attr, '$.lastVisitDate') else 'N/A' end) " \
+            "when type = 'S' then concat((case when json_length(attr, '$.events') is not null " \
+            "then json_length(attr, '$.events') else 0 end), ' events') end as description " \
+            "from locations"
+    cur.execute(query)
+    row_headers=[x[0] for x in cur.description] 
+    rv = cur.fetchall()
+    for result in rv:
+        json_data.append(dict(zip(row_headers,result)))
+   
+   if request.method == 'POST':
+       name = request.json['name']
+       description = request.json['description']
+       type = request.json['type']
+       latitude = request.json['latitude']
+       longitude = request.json['longitude']
+       attr = request.json['attr']
+       query = "insert into locations (name, description, type, latitude, longitude, attr) values (?, ?, ?, ?, ?, json_compact(?))"
+       cur.execute(query,(name, description, type, latitude, longitude, attr))
+       json_data = { 'success': True }
+
+   return json.dumps(json_data), 200, {'ContentType':'application/json'} 
+
+@locations.route('/api/locations/restaurant', methods=['GET'])
+def get_restaurant():
+   id = request.args.get('id')
+   conn = mariadb.connect(**config)
+   cur = conn.cursor()
+   json_data = []
+   query = "select " \
+            "name, " \
+            "json_value(attr,'$.details.foodType') as foodType, " \
+            "json_value(attr,'$.details.menu') as menu, " \
+            "json_query(attr,'$.favorites') as favorites " \
+            "from locations " \
+            "where id = ?"
+   cur.execute(query, [id])
+   row_headers=[x[0] for x in cur.description] 
+   result = cur.fetchone()
+   json_obj=dict(zip(row_headers,result))
+   return json.dumps(json_obj), 200, {'ContentType':'application/json'} 
+
+@locations.route('/api/locations/restaurant/favorites', methods=['POST'])
+def add_restaurant_favorite():
+    id = request.json['locationId']
+    details = request.json['details']
+    conn = mariadb.connect(**config)
+    cur = conn.cursor()
+    query = "update locations set attr = json_array_append(attr, '$.favorites', json_compact(?)) where id = ?"
+    cur.execute(query,[details,id])
+    return json.dumps({ 'success': True }), 200, {'ContentType':'application/json'} 
+
+@locations.route('/api/locations/sportsvenue', methods=['GET'])
+def get_sportsvenue():
+   id = request.args.get('id')
+   conn = mariadb.connect(**config)
+   cur = conn.cursor()
+   json_data = []
+   query = "select " \
+            "name, " \
+            "json_value(attr,'$.details.yearOpened') as yearOpened, " \
+            "json_value(attr,'$.details.capacity') as capacity, " \
+            "json_query(attr,'$.events') as events " \
+            "from locations " \
+            "where id = ?"
+   cur.execute(query, [id])
+   print(query)
+   row_headers=[x[0] for x in cur.description] 
+   result = cur.fetchone()
+   json_obj=dict(zip(row_headers,result))
+   return json.dumps(json_obj), 200, {'ContentType':'application/json'} 
+
+@locations.route('/api/locations/sportsvenue/events', methods=['POST'])
+def add_sportsvenue_event():
+    id = request.json['locationId']
+    details = request.json['details']
+    conn = mariadb.connect(**config)
+    cur = conn.cursor()
+    query = "update locations set attr = json_array_append(attr, '$.events', json_compact(?)) where id = ?"
+    cur.execute(query,[details,id])
+    return json.dumps({ 'success': True }), 200, {'ContentType':'application/json'} 
+
+@locations.route('/api/locations/attractions', methods=['PUT'])
+def attractions():
+    locationId = request.args.get('id')
+    lastVisitDate = request.args.get('dt')
+    conn = mariadb.connect(**config)
+    cur = conn.cursor()
+    query = "update locations set attr = json_set(attr,'$.lastVisitDate', ?) where id = ?"
+    cur.execute(query,[lastVisitDate,locationId])
+    return json.dumps({ 'success': True }), 200, {'ContentType':'application/json'} 
diff --git a/src/client b/src/client
@@ -0,0 +1 @@
+Subproject commit 68cb67c22cfd6f86a0c9a59bac999a87c750f032

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[submodule "src/client"]`
	`2`	`+ path = src/client`
	`3`	`+ url = https://github.com/mariadb-developers/places-app-client.git`