This guide is here to help you start up the webserver, connect to the swagger docs page and test the API endpoints
The API is wrtten in python and so to start it up, you need to install python on to your system.
For brevity sake, I have included a few videos the show the installation process indepth for both Windows and MacOS systems
Windows: https://www.youtube.com/watch?v=yivyNCtVVDk
MacOS: https://www.youtube.com/watch?v=3-sPfR4JEQ8
On Windows, make sure you check the box that says add python.exe to PATH. very important. If there is an option confirming the installation of pip, make sure its checked.
Now for running python:
If python has been properly installed, you can probably run a python script from the desktop.
On Windows just by double clicking on a python file and on macOS by right click and select Open With -> Python Launcher.
(NOTE: I have never ran code like this. I cannot guarantee it'll work, but I guess it should :|)
The problem with this method of running python is that depending on the script being run, its hard to capture output and thus harder to debug.
I suggest using the Command Prompt/terminal for running python programs.
Here is some help on command lines:
Windows/Command prompt: https://www.youtube.com/watch?v=A3nwRCV-bTU
MacOS/terminal: https://www.youtube.com/watch?v=FfT8OfMpARM
If you decided to opt out of using a command line, all you would need to do is first click on install.py in the directory to install the required dependencies and the click on run.py to run the web server.
(NOTE: Doing this will probably spawn command lines, but they will probably dissapear once the program has been terminated)
If you decide to use a command line. First navigate to the project's folder.
Then run either python install.py or pip install -r requirements.txt to install the dependencies
After that terminates, run python run.py. This will start up the webserver which will stay on until to terminate the program.'
When you run run.py, hopefully you'll see this output.
Now that URL: http://127.0.0.1:8000 is the URL through which we can interact with the API.
To clarify one thing. This is not really an interface I designed. It's a docs UI that is autogenerated by the fastapi dependence. But it is very verbose and has a lot of functions, so it makes do as a testing utility.
In any web browser, go to http://127.0.0.1:8000/docs and you should see this page:
The only thing of importance are the colored rows. Those are the endpoints, the URLS through which the user can interact with the webserver.
You should have 6 endpoints, you can ignore the one labeled as root. The rest of the endpoints relate to the Inventory management.
/items: Gets all data from all items in the inventory/items/{id}: Gets the data of a specific item./add: Adds a new item to the inventory/edit/{id}: Edit a specific item with new data/remove/{id}: Remove a specific item from the inventory
Some quick unimportant information on the endpoints, just like we added docs to the base URL to get to the current page. You can add these endpoints to the base URL to get to these 'pages'. Some endpoints have {id} and that should be replaced with the id number when actually accessing the endpoints. Other data is sent to the web server is RAW JSON request data. Luckily, we don't really have to worry about using raw requests and data because the docs page has a GUI utility for it.
If you click on any endpoint, you should see this:
It's divided into two sections parameters and responses. Parameters is what we give to the webserver and the responses is what the webserver gives back to us.
In this docs page to execute any endpoint, click the Try it out button on the top right.
In this example, I'm showing off the /items endpoint, so there are no parameters to input. Then I can click Execute to send the request and I get:
The main thing to check for is a Code of 200 and then the Response Body. This is data we get back from the server and as you can see, it's empty since I have not added anything to the database yet.
First lets add an item to the inventory so click on the add endpoint and click Try it out:
You will see an input box for JSON data. JSON stores data as Key-Value pairs, so name, description, and quantity are the keys and the stuff next to it is the data.
Right now they have the default values provided. You can change them and they should match the format I have below.
(NOTE: All text data is should be encapsulated in "quotes" and every key-value pair needs a comma afterwards)
Now click on execute and scroll down to the response. Hopefully you see something like this:
This is the actual data on the database that has been returned back to the user.
You can now execute /items or /items{id} with the parameter set to that id, and you can see the same data.
You can add more items to the inventory and if you run /items you will see the others
Try out the other endpoints like /remove and /update{id} to get how they work on the whole.
This now concludes the end of my guide. Please feel free to ask me questions any time, i'm happy to help. I will now go to sleep :)