{"id":21149747,"url":"https://github.com/alphabetsalphabets/web-api","last_synced_at":"2026-05-22T14:06:22.357Z","repository":{"id":145897610,"uuid":"330655403","full_name":"AlphabetsAlphabets/Web-API","owner":"AlphabetsAlphabets","description":"A RESTful web API","archived":false,"fork":false,"pushed_at":"2022-01-21T01:58:11.000Z","size":11743,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-21T08:08:22.963Z","etag":null,"topics":["flask","flask-restful","python","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlphabetsAlphabets.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2021-01-18T12:13:01.000Z","updated_at":"2022-01-21T01:55:39.000Z","dependencies_parsed_at":"2023-07-24T08:30:32.423Z","dependency_job_id":null,"html_url":"https://github.com/AlphabetsAlphabets/Web-API","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlphabetsAlphabets%2FWeb-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlphabetsAlphabets%2FWeb-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlphabetsAlphabets%2FWeb-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlphabetsAlphabets%2FWeb-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlphabetsAlphabets","download_url":"https://codeload.github.com/AlphabetsAlphabets/Web-API/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243589335,"owners_count":20315479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","flask-restful","python","rest-api"],"created_at":"2024-11-20T09:41:52.008Z","updated_at":"2026-05-22T14:06:12.345Z","avatar_url":"https://github.com/AlphabetsAlphabets.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Table of contents\nTopic | description |\n--- | ---- |\n| [Python learning resources](https://github.com/YJH16120/Web-API#Python-learning-resources) | You are required to have at least have intermediate knowledge of Python. Learing resources are provided here. |\n| [File structure](https://github.com/YJH16120/Web-API#familiarize-yourself-with-the-directory-structure) | Directory structure, and explanation on which file goes where. |\n| [How to setup development environment](https://github.com/YJH16120/Web-API#configuring-the-development-environment) | Tells you how to setup your development environment. |\n| [Foreword](https://github.com/YJH16120/Web-API#foreword) | Information on how to proceed.\n| [What library this project is dependant on.](https://github.com/YJH16120/Web-API#Based-on) | Explains which libray the project is depedant on.\n| [Finding where anything is defined](https://github.com/YJH16120/Web-API#finding-where-anything-is-defined) | Useful for when you want to know the inner workings of a function |\n| [Creating a new endpoint](https://github.com/YJH16120/Web-API#creating-a-new-endpoint) | A guide on how to create a new endpoint |\n| [Verifying a user's api key](https://github.com/YJH16120/Web-API#verifying-a-users-api-key) | How to verify a user's api key |\n| [Writing documentaiton](https://github.com/YJH16120/Web-API#writing-documentation) | How to write documentation that complies to PEP8 standards |\n| [Type hinting](https://github.com/YJH16120/Web-API#type-hinting) | How to write type hints and return types |\n\n---\n##  Python learning resources\nThis list contains a mix of videos to watch and text to read.\n\n### Learing Python\n- [Python crash course](https://www.youtube.com/watch?v=rfscVS0vtbw\u0026t=10686s) by Mike Dane\n\n- Corey Schafer for general Python tutorials where he goes in-depth to each concept.\n    - [Python for beginners](https://www.youtube.com/watch?v=YYXdXT2l-Gg\u0026list=PL-osiE80TeTskrapNbzXhwoFUiLCjGgY7)\n    - [OOP](https://www.youtube.com/watch?v=ZDa-Z5JzLYM\u0026list=PL-osiE80TeTsqhIuOqKhwlXsIBIdSeYtc) (Object oriented programming)\n\n### Building a REST API with Flask Restful\n- [Building an api with Flask Restful by Tim Russica](https://www.youtube.com/watch?v=GMppyAPbLYk). This will teach you how to work with Flask Restful\n\n- [Documentation of Flask Restful](https://flask-restful.readthedocs.io/en/latest/), for a more in-depth explanation of how things work.\n\n---\n## Familiarize yourself with the directory structure\n```\nWeb API\n|   \n+---docs\n|       \n+---env-api\n|   |   \n|   +---endpoints\n|   |   |   \n|   |   \\---databases\n|   |           \n|   \\---QA\n|           \n\\---src\n\n```        \n## Root of the project\nWeb API is the root of the project, and from this point onwards whenever I say \"at the root of the project\" or reference the root of the project in any capacity. Always assume that you have to go to Web API, unless specified otherwise.\n\n## docs\nDocs contain documentation. Code examples can be found there.\n\n## env-api\nThis is where the `endpoints` directory is, and where *all* endpoints reside. It's also where `QA` is found, quality of life files/modules are\nkept there.\n\n## endpoints\nThis is where **all** endpoints are kept. Make sure it goes into that folder.\n\n## databases\nThis is where the sqlite3 databases are kept. These are used to simulate, a client's activity.\n\n## src\nThis folder contains the main source file. Where `main.py` is the main source file.\n\n---\n## Configuring the development environment\n1. Have python 3.9 and above installed.\n2. make sure pip is working, to test run `pip --version` in a terminal. If it shows you the version number proceed, if not then fix it.\n3. Have the [git](https://git-scm.com/downloads) CLI installed.\n4. Run the following command: `git clone 'https://github.com/YJH16120/Web-API'`  \n\nFrom this point onwards make sure you perform all commands in the root of the project. Unless specified otherwise  \n\n5. Cut the contents from the env-api directory, except pyvenv.cfg. Keep it either in your clipboard, or paste it some where else for safe keeping. Then delete the folder. The contents will be needed later.\n\n6. Run the following commands to create a virtual environment (make sure you're in the root when running these commands):\n    - run `pip install venv`\n    - `py -m venv env-api`\n    - For powershell: `env-api\\Scripts\\active`, for CMD: `activate`\n    - go into `env-api\\` then paste the contents from your clipboard into the directory.\n    - `pip install -r requirements.txt`, this will install the appropriate dependancies.\n\nIt is worth noting that if you run this python code through visual studio code (VSC) by clicking the [play button](https://i.postimg.cc/D0ykRP8k/image.png)\nprovided by the downloadable python extension, **most** endpoints that require the use of paths will fail. So you **must** always run the main source file\nfrom a terminal instead. That is because each source file sees itself as the centre of the project, and everything else as relative to it, whereas if you\nrun it in VSC the root will be the centre of the project instead of each source file being the centre. Which is why it will most likely fail.\n\n7. Check if you've setup everything correctly. Go to the root, then run `py src/main.py`\nIf there are no errors and everything is fine, it means that you've successfully configured your environment to develop the API.\n\n---\n## Foreword\nMake sure to update the variables `self.schema` and `self.table` in **all** endpoints it appears in (all endpoints are located in env-api/endpoints/). It will usually appear in the `__init__` function of all endpoints. This is what it will look like int the `__init__` function.\n\n```python3\nclass endpoint:\n    def __init__(self):\n        # code ...\n```\n\nchange the `__init__` function to:\n```python3\ndef __init__(self):\n    # code ...\n    self.conn, self.cursor = Database.connect(.., ..)\n    self.schema = \"schema\"\n    self.table = \"table\"\n```\n\nOf course set `self.schema` and `self.table` to valid names. **Do not** alter/modify any other code within the `__init__` method unless it's within a try/except block\n\n## Based on\nThis project is based on [flask restful](https://flask-restful.readthedocs.io/en/latest/index.html). Without this package it would not be possible to develop the api the way it is.\n\n---\n\n## Finding where anything is defined.\n- All endpoints are located in the env-api/endpoints/ directory. \n- Functions related to connecting to a database, encryption, and api key verification is located in the env-api/QA/ directory.\n\nIf your IDE or text editor supports go-to definition, I suggest you go-to defininition instead of manually locating where each file is. Especially if you're\nnew to the project\n\n## Creating a new endpoint\nCreate a new endpoint in the env-api/endpoints/ directory. And lay it out in the following structure\n```python3\nfrom flask_restfull import Resource\n\nclass Example(Resource):\n    def __init__(self):\n        \"\"\"Handle initilization\"\"\"\n        self.conn, self.cursor = Database.connect(\"host\", \"username\", \"password\", \"schema\")\n\n    def \u003crequest\u003e(self, arg1, arg2):\n        \"\"\"process the request.\"\"\"\n        pass\n```\n- `self.conn` is the connection to the MySql database\n- `self.cursor` is the cursor to the MySql database\n- `\u003crequest\u003e` is the type of request. Change `\u003crequest\u003e` to GET if the endpoint is going to process a GET request. For a template refer to example.py (docs/example.py)\n\nMy suggestion instead of writing in the string literal into the password field. A function that reads from a file such as config.ini should be used to store that information. And that file should be included in the .gitignore file. Here is an [example](https://github.com/YJH16120/Web-API/blob/master/env-api/QA/database.py)(scroll to the end of the file, and look for `getPassword`).\n\n---\n## Setting up a url resource\nIf for example, we want to make a resource that uses logic from the `Example` class, we need to create a url resource. Assume the file that the `Example` class is from is called `example.py`\n\nI'm going to assume you are some what familiar with [Flask](https://flask.palletsprojects.com/en/1.1.x/), as least up to creating a Flask app.\n\nFrom a main source file do the following:\n```python3\nfrom flask_restful import Api\nfrom example import Example\n\napp = Flask(__name__)\napi = Api(app)\n\napi.add_resource(Example, \"/example/\u003cstring:arg1\u003e/\u003cstring:arg2\u003e\")\n```\nWhen you run main source file with `py main.py` you can go to the link printed onto the terminal and append it with \"example/1/2\". In order to access the endpoint.\n\nKeep in mind that in `/example/\u003cstring:arg1\u003e/\u003cstring:arg2\u003e` (I will call this string resource from this point onwards), the number of arguments in resource must match the number of arguments as specified in the class.\n\nIn `Example` the method `\u003crequest\u003e` has two parameters `arg1`, and `arg2`. As you can see resource reflects that. If `\u003crequest\u003e` instead has `a`, and `b`. Resource would be changed to `/example/\u003cstring:b\u003e/\u003cstring:a\u003e`.\n\nThe parameters in resource and the method **must** match. Or an exception will be thrown.\n\n---\n## Accepting data from multiple locations\nWhen making a HTTP request information can be sent in through the headers or various other locations.\n\nTo do so we must modify the `Example` class' `__init__` method. And import another class.\n```python3\nfrom flask_restful import reqparse\n\ndef __init__(self):\n    \"\"\"Handle initilization\"\"\"\n    self.conn, self.cursor = Database.connect(\"host\", \"username\", \"password\", \"schema\")\n    parser = reqparse.RequestParser()\n    parser.add_argument(\"header1\", type=str, location=\"headers\")\n```\nThis modification will make it so that you can get information from the header named \"header1\"\n\nFor a full list of locations, refer to the [flask restful](https://flask-restful.readthedocs.io/en/latest/reqparse.html?highlight=headers) documentation\n\n---\n## Verifying a user's api key\nValidating a user's api key. In order for a user to get their api key, they must first go through the login endpoint (env-api/endpoints/login.py) and then the key must be passed\ninto the `verifyKey()` method provided in QA/key.py.\n```python3\nKey.verifyKey(\"username\", \"abc123\") \n```\n\n## Writing documentation\nDocumentation is important. Make sure to include it in the following format. When creating classes, and it's methods.\n```python3\nfrom typing import Union\n\nclass Example:\n    \"\"\"This class provides functions to add, and divide\n\n    # Functions\n    ### public\n    - subtract \n\n    ### private\n    - add \n    \"\"\"\n\n    def __add(self, number1: Union[int, float], number2: Union[int, float]) -\u003e Union[int, float]:\n        \"\"\"Adds two numbers together\n\n        ---\n\n        # Parameters\n        \n        ### number1\n        the first number\n\n        ### number2\n        the second number\n        \"\"\"\n\n        return number1 + number2\n\n    def divide(self, number1: int, number 2: int) -\u003e Union[int, str]:\n        \"\"\"Performs division\n\n        ---\n\n        # Parameters\n        \n        ### number1\n        the first number\n\n        ### number2\n        the second number\n\n        ---\n\n        # Exceptions\n        - ZeroDivisionError: This occurs when you divide by 0\n\n        ---\n\n        # Example(s)\n        ```python3\n        num1 = 2\n        num2 = 2\n        result = Example().divide(num1, num2)\n        print(result) # 1\n        \"\"\"\n        try:\n            return number1 / number2\n        except ZeroDivisionError:\n            return \"cannot divide by zero\"\n```\nMake sure to include a brief summary about what the class does, and list down all their class functions. And always make sure to include a brief summary about the class and function first.\n\nThen in each function, give a brief description, followed by a brief explanation for each parameter, and if the function has a chance to throw an exception include an exception section as well. Optionally an examples section, to illustrate what the function does in greater detail. Or to act as supporting evidence.\n\nSeparate each section with three `-`'s \n\nAnd make sure to include type hinting. Refer to the python documentation about the [typing](https://docs.python.org/3/library/typing.html) module\n\n## Type hinting\nType hinting is important because it tells the user what types the function parameters expect, and what the return type is.\n```python3\ndef foo(a: str, b: int) -\u003e str\n    return str + str(int)\n```\nThis tells the user that `foo` has two parameters `a`, and `b`. And that `a` accepts a string, `b` accepts an interger and the function returns a string.\nAnd if no return type is specified it is assumed that the function does not return anything.\n\nfor advanced type hinting, such as a parameter accepting either a boolean or an interger the [typing](https://docs.python.org/3/library/typing.html) module is required.\n```python\nfrom typing import Union\ndef bar(a: Union[int, bool]) -\u003e bool:\n    return bool(a)\n```\n\n\n# Sugestions\n- Instead of creating a new table for api keys add a new column in the tsc_office.tap table, called api key. More details in (QA/key.py)\n- Scrap the generic insert endpoint (env-api/endpoints/insertGeneric.py)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphabetsalphabets%2Fweb-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falphabetsalphabets%2Fweb-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphabetsalphabets%2Fweb-api/lists"}