CYA

DEPRECATED: The database is removed and this project is no longer active.

A RESTful API built in Flask for spaced repetition studying.

Table of Contents

• Demo
• Motivation
• Features
• API Reference Index
  1. User
     • POST /register
     • POST /login
     • POST /logout
     • POST /refresh
  2. Board
     • GET /boards
     • GET /<board_name>
     • POST /<board_name>
     • PUT /<board_name>
     • DELETE /<board_name>
  3. Card
     • GET /cards
     • GET <board_name>/cards
     • DELETE <board_name>/cards
     • GET <board_name>/<card_name>
     • POST <board_name>/<card_name>
     • PUT <board_name>/<card_name>
     • DELETE <board_name>/<card_name>
  4. Card-SM-Info
     • GET <board_name>/<card_name>/all-sm2-info
     • POST <board_name>/<card_name>/sm2-info
     • PUT <board_name>/<card_name>/sm2-info/<id>
     • DELETE <board_name>/<card_name>/sm2-info/<id>
• Quick Start
• Technologies Used
  1. RESTful API
  2. Testing
     • Coverage Details
  3. Cloud
  4. Env/Config
• Project Structure
• Database Structure

Demo

OpenAPI/Swagger UI document deployed at https://cya-api.herokuapp.com/apidocs/ (There is no UI that corresponds to the API at the moment.)

Motivation

The reason behind making this API is for my own studying. I've always been interested in self-improvement, time management and effective learning, so I've been practicing spaced repetition more and more to help myself learn Data Structure and Algorithms.

And I thought it would be a great opportunity for me to learn building a fullstack web application and dig more into the science of spaced repetition, so I started off with building the backend first, which is the REST API you see now.

If you are curious of what spaced repetition is, check this out: https://ncase.me/remember/

Features

• API follows the RESTful design.
• Allows multiple users to access the API.
• API calculates the next review date for whatever you are learning based on the spaced repetition learning algorithm SuperMemo-2.
• OpenAPI/Swagger UI supported for simpler access for developers.

API Reference Index

User Model

Field	Description
id	The user's id
username	The user's unique username

POST /register

Register a user based on the username and password the user provided.

Resource URL

https://cya-api.herokuapp.com/register

Resource Information

Response format	JSON
Requires authentication?	No
Requires request body?	Yes

Request body key	Required	Type
username	Yes	String
password	Yes	String

POST /login

Logins the user based on the username and password the user provided.

Resource URL

https://cya-api.herokuapp.com/login

Response format	JSON
Requires authentication?	No
Requires request body?	Yes

Request body key	Required	Type
username	Yes	String
password	Yes	String

POST /logout

Resource URL

https://cya-api.herokuapp.com/logout

Response format	JSON
Requires authentication?	Yes

POST /refresh

Resource URL

https://cya-api.herokuapp.com/refresh

Response format	JSON
Requires authentication?	Yes

---

Board Model

Field	Description
id	The board's id.
name	The board's unique name.
user_id	The user id of the user that owns this board.

GET /boards

Resource URL

https://cya-api.herokuapp.com/boards

Response format	JSON
Requires authentication?	Yes

GET /<board_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>

Response format	JSON
Requires authentication?	Yes

POST /<board_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>

Response format	JSON
Requires authentication?	Yes

PUT /<board_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>

Response format	JSON
Requires authentication?	Yes

DELETE /<board_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>

Response format	JSON
Requires authentication?	Yes

---

Card Model

Field	Description
id	The card's id.
name	The card's unique name.
tag	The category tag that attaches to the card
quality	The quality of the review. Check here for more detail description.
last_review	The date of the last time this card is reviewed.
next_review	The date of the next time this card should be reviewed.
board_id	The board id of the board that card belongs to.

GET /cards

Note: This endpoint will most likely be removed and change the today resource to a query parameter instead.

Resource URL

https://cya-api.herokuapp.com/cards

Response format	JSON
Requires authentication?	Yes

Parameters	type	value	required
today	boolean	true/false	No

GET /<board_name>/cards

Resource URL

https://cya-api.herokuapp.com/<board_name>/cards

Response format	JSON
Requires authentication?	Yes

Parameters	Type	Value	Required
today	boolean	true/false	No

DELETE /<board_name>/cards

Note: The API is in Alpha, so please use this with caution, once it's deleted it's gone. There will be warnings in the future.

Resource URL

https://cya-api.herokuapp.com/<board_name>/cards

Response format	JSON
Requires authentication?	Yes

GET /<board_name>/<card_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>

Response format	JSON
Requires authentication?	Yes

POST /<board_name>/<card_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>

Response format	JSON
Requires authentication?	Yes

PUT /<board_name>/<card_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>

Response format	JSON
Requires authentication?	Yes

DELETE /<board_name>/<card_name>

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>

Response format	JSON
Requires authentication?	Yes

---

Card-SM-Info Model

This is for the card's SuperMemo2 information.

Field	Description
id	The card's id.
quality	The quality of the review. Check here for more detail description.
new_interval	The card's new calculated interval value using the SuperMemo-2 algorithm.
new_repetitions	The card's new calculated repetitions value using the SuperMemo-2 algorithm.
new_easiness	The card's new calculated easiness value using the SuperMemo-2 algorithm.
last_review	The date of the last time this card is reviewed.
next_review	The date of the next time this card should be reviewed.
board_id	The board id of the board that card belongs to.

GET /<board_name>/<card_name>/all-sm2-info

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>/all-sm2-info

Response format	JSON
Requires authentication?	Yes

POST /<board_name>/<card_name>/sm2-info

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>/sm2-info

Response format	JSON
Requires authentication?	Yes

PUT /<board_name>/<card_name>/sm2-info/<id>

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>/sm2-info/<id>

Response format	JSON
Requires authentication?	Yes

DELETE /<board_name>/<card_name>/sm2-info/<id>

Resource URL

https://cya-api.herokuapp.com/<board_name>/<card_name>/sm2-info/<id>

Response format	JSON
Requires authentication?	Yes

Quick Start

Coming soon...

Technologies Used

RESTful API

📋 API
   :pushpin: Flask
   :pushpin: Flask-RESTful

📋 ORM (Object Relational Mapper)
   :pushpin: Flask-SQLAlchemy

📋 Data Serialization
   :pushpin: Flask-Marshmallow

📋 Database Migration
   :pushpin: Flask-Migrate (alembic)

📋 Token Authentication
   :pushpin: Flask-JWT-Extended

📋 Spaced Repetition Algorithm
   :pushpin: SuperMemo2 (My own package!)

---

Testing

📋 Unit & Functional Testing
   :pushpin: Pytest (Built-in Python Library)
   :pushpin: Pytest-Cov

Coverage Details

---

Cloud

📋 Service Hosting
   :pushpin: Heroku

📋 Database
   :pushpin: AWS RDS

---

Env/Config

📋 Python-Dotenv
   :pushpin: For easier local configurations using dotenv file.

Project Structure

Database Structure