added documentation for API

README.md

@@ -2,19 +2,25 @@ One of the key deliverables for Work Package 6 of the COPIM project is "an onlin
 
 The ExPub Compendium will build on this review of tools to present a resource for a researcher, artist, or publisher looking to try experimental publishing. From our preliminary design discussions, we have plans to include not only software tools that can be used to do experimental publishing but examples of experimental publications, practices of experimental publishing, publishers who have done some form of experimental publishing, and sensitivities involved in experimental publishing.
 
-## Application structure
+## application structure
 
 The ExPub Compendium is a Python application using the [Flask](https://flask.palletsprojects.com/en/2.2.x/) framework to render as a website and to provide functions around user authentication and login as well as retrieving data from the underlying database. The Flask framework uses a few HTML template pages to render different pages efficiently based on routes defined in Python files. These template pages use a fairly basic [Bootstrap 5](https://getbootstrap.com/) grid design which allows for responsive design using in-built CSS and HTML elements. 
 
 The database is a MariaDB SQL database with a basic structure of Resources, Relationships, and Users. Resources are divided into tools, practices, and books and the table contains fields for these various types of resources. Relationships defines the links between resources using the resource ID in the Resource table: these are rendered on the site as connections between, say, a tool and a practice. Users contains the site's users with basic details like email address and hashed password. This simple structure provides flexibility for displaying resources with filters and to illustrate the connections between various resources. 
 
-### to deploy environment
+### RESTful API
 
-#### environment files
+The application has a simple RESTful API deployed using Marshmallow to define schemas based on the SQLAlchemy database models. It allows a simple JSON export of users (login required), tools, practices, and books.
+
+The API is relatively open and is available at ./api 
+
+## deployment instructions
+
+### environment files
 
 To deploy this environment, first copy env.template to a new file, env.dev. Fill in the appropriate environment variables.
 
-#### Docker Compose
+### Docker Compose
 
 In the command line, navigate to the directory where this repository is stored on your local machine and run:
 
@@ -28,7 +34,7 @@ To take down the environment, run:
 
 `docker-compose down`
 
-#### populating the database
+### populating the database
 
 To intially create the database and a database user:
 
@@ -49,13 +55,13 @@ You can then use database_functions.sh and an SQL file to populate the database
 
 `./database_functions -i ./db_imports/toolkit_db_20230112.sql`
 
-## Database functions 
+## database functions 
 
 This repository contains a shell script to perform various database functions including importing a whole database from SQL file, exporting the database in SQL, exporting individual tables as tab-delimited txt file, and importing individual tables from tab-delimited txt file. 
 
 Run `./database_functions -h` to see the instructions for this script. 
 
-## Legacy instructions:
+### legacy database instructions:
 
 The following is no longer required in Flask-SQLAlchemy 3. See https://stackoverflow.com/questions/73968584/flask-sqlalchemy-db-create-all-got-an-unexpected-keyword-argument-app
 

web/app/__init__.py

@@ -17,7 +17,7 @@ import os
 # initiate SQLAlchemy so we can use it later in our models
 db = SQLAlchemy()
 
-# initiate Marshmallow
+# initiate Marshmallow for defining schemas for JSON export
 ma = Marshmallow()
 
 # initiate Moment for datetime functions

web/app/api.py

@@ -14,6 +14,21 @@ from .schemas import UserSchema, ToolSchema, PracticeSchema, BookSchema
 
 api = Blueprint('api', __name__)
 
+# function to get different types from the Resource database table
+def get_resource_json(type):
+    resources = Resource.query.filter_by(type=type)
+    if (type=='tool'):
+        resources_schema = ToolSchema(many=True)
+    elif (type=='practice'):
+        resources_schema = PracticeSchema(many=True)
+    elif (type=='book'):
+        resources_schema = BookSchema(many=True)
+    result = resources_schema.dump(resources)
+    # return all rows as a JSON array of objects
+    result = jsonify(result)
+
+    return result
+
 # route for api page
 @api.route('/api')
 def api_page():
@@ -30,20 +45,6 @@ def get_users():
     # return all rows as a JSON array of objects
     return jsonify(result)
 
-def get_resource_json(type):
-    resources = Resource.query.filter_by(type=type)
-    if (type=='tool'):
-        resources_schema = ToolSchema(many=True)
-    elif (type=='practice'):
-        resources_schema = PracticeSchema(many=True)
-    elif (type=='book'):
-        resources_schema = BookSchema(many=True)
-    result = resources_schema.dump(resources)
-    # return all rows as a JSON array of objects
-    result = jsonify(result)
-
-    return result
-
 # route for exporting all tools in database
 @api.route('/api/tools')
 def get_tools():