Develop API doc

[jacob-macleod]

Develop documentation in a folder for the documentation of the API. Comments explaining the API are at the start of each API function, so it should be a fairly straightforward fix

[rajesh-aravind]

Hi, I may be able to contribute to the documentation for this API. Can you please share the document, I'll have a look at it and share my insights for the documentation. ~Thanks

[jacob-macleod]

Great, thanks! The code storing API information is stored in src/routes/api. This includes:

• authentication.py
• card_management.py
• statistics.py

Each of the API routes require a URL being navigated to, and a request sent with json. There should be comments below each method to explain what json data needs to be sent.

If you could write the documentation in markdown files, in some sort of docs folder in the root repository of the project, or whatever location makes sense to you, that would be great.

Let me know if you need any more information

[rajesh-aravind]

Hi, I attempted to document the method for the first file authentication.py. Attached is the document in the section. Can you please take a look and let me know if this is correct? The issue I faced am not able to test in POSTMAN since there is no URL given in the code. ~Thanks Sample1.docx

[jacob-macleod]

Looks good, thanks! Would you mind writing it in markdown though, because I don't think .docx files can be rendered in github without being downloaded. (I could be wrong though).

In terms of the URL, I'm writing code to allow error checking for each method - it'll check if you've supplied the right json data. In addition, it'll check things like dates are in the right format. That should be ready and merged soon, and I'll let you know when it is. Once I've done that, I'll let you know the URL - I don't want to post it publicly yet because I need to add the error checking, so requests could probably mess the test data format I have stored so far. (Admittedly it is still avaliable on the Internet at the moment)

[jacob-macleod]

I've now added the API verification, earlier than expected. The URL is http://dolphinflashcards.com All api requests have http://dolphinflashcards.com/api/something because the base API serves HTML pages for the front end UI.

In terms of the error checking, before each request, a json format is given which the code then checks against. This looks like the following:

    expected_format = {
            "userID": "",
            "cardStatus": CARD_STATUS,
            "cardStreak": NUMBER,
            "currentIndex": NUMBER,
            "lastReview": DATE_REGEX,
            "maxIndex": NUMBER,
            "reviewStatus": REVIEW_STATUS_REGEX
        }

The variables mentioned here are regex patterns from src/routes/api/regex_patterns.py. Each pattern has a comment explaining it, or you can use ChatGPT to learn more about it. (That's how I got the pattern in the first place). Each pattern is also tested in testing/test_regex.py, so that can give more information on example usage.

The code checks to see:

• Exactly the right attributes are supplied in the json, in the right order
• If the value for the attribute is not "", assume it is a regex pattern and compare the example request regex to the actual request

The example request and actual request are tested in the function check_request_json, which returns True if there is not error and an error message if there is one. If there is an error message, this json is returned to the user:

return jsonify(
    {"error": result + ". The request should be in the format: " + str(expected_format)}
), 400

Let me know if you have any questions

[rajesh-aravind]

Thanks for the updates Jacob, I'll convert the doc to markdown. I wanted to know whether I'm on the correct path. With the above information, I'll proceed to document the other two files. I'll reach out in this section if I have any questions.

~Thanks Rajesh

[rajesh-aravind]

Hi, I have kept the authentication api document in my repository [https://github.com/rajesh-aravind/API-Documentation.git]. Can you please link or copy it from there. I was not able to copy the file in your project repository.

Meanwhile when I tried access to the other two files [card_management.py) and [statistics.py) it gives me a 'File not found" error.

[jacob-macleod]

Ah sorry - I renamed the src folder. The following links should work

• card_management.py
• statistics.py

I'll add your authentication file in a bit

[kenudeh]

Hi @jacob-macleod and @rajesh-aravind, I came across this issue a week ago and took an interest in it. Since there hasn't been much activity on it, I thought I could assist @rajesh-aravind a little. The documentation for the endpoints in statistics.py can be found here

If there are corrections or observations about the document, I'll gladly effect them. Have a happy weekend ahead everyone!

Regards.

[jacob-macleod]

Thanks for your work on this, @kenudeh! Just a few slight things: First, even if data in the database should be a number, its stored as a string regardless. This is because I didn't know if Google Firebase handled non-string values since I hadn't used it before. It probably does, and I should probably change it to have better datatype, but for now, every Type in the table Request Body Parameters should be a String.

For the example response in /calculate-card-stats, it looks like there's a " which isn't closed in the line: "maxIndex": “integer,

Finally, for the request example in /calculate-streak, I don't think ?increase:true is correct syntax - I think it should be ?increase=true

Thanks again for your work on this! Once you've made those few tweaks, would it be easier if I added the file to the repository myself, mentioning you as the author, or would it be easier for you to fork the repo and make a new branch with the changes, then create a merge request?

[kenudeh]

Thank you for the feedback @jacob-macleod, I'll make the necessary changes and send in a merge request by tomorrow. Happy you welcomed my little help.

[jacob-macleod]

@rajesh-aravind @kenudeh I've made some changes to make the project easier to contribute to without setting up a server and added CONTRIBUTING.md. The backend uses Python and Flask, and the front end uses React.js. If you wanna contribute, feel free to look at the existing issues or make your own!

[jacob-macleod]

And just a general note, documentation still needs to be written for https://github.com/jacob-macleod/Flashcard-App/blob/main/backend/routes/api/card_management.py

[kenudeh]

Alright, I'll start working on the card_management.py documentation this weekend. It should be ready by tomorrow.

[kenudeh]

Hi @jacob-macleod! Checking to see if there are documentation requirements at this time.

[jacob-macleod]

Ah thanks - yeah, the endpoints in goals.py need to be documented. Note that instead of making a branch from the main branch, could you make it from development? (To solve merge conflicts - when I merged the changes including goals.py they were on a long term feature branch which caused loads of conflicts)

[kenudeh]

Alright, I'll take note of that while making a branch for goals.py's documentation. It should be ready by Wednesday. Sorry for not getting back to you sooner; I had a busy weekend.

[jacob-macleod]

I'm closing this because it's included in the issue to convert documentation to mintlify