Issue #82: Create lifecycle events routes

[snakedye]

API Endpoints

• [ ] POST submit : Send the latest state of a form to the database.

  The state can either be final or transient.

sequenceDiagram
    title FertiScan Submit Form
    participant C as Client
    participant FE as Frontend
    participant BE as FertiScan
    participant DS as DataStore
    participant DB as SQL

    C ->> FE: submit_form()
    FE ->> BE: POST /submit JSON
    note right of BE: Authorization: Basic (email as user_id)\nContent: JSON (Form)

    alt form.confirm == true
        BE ->> DS: submit_final_form()
        note left of DS: the final version of\n the form.
    else
        BE ->> DS: submit_update_form()
        note left of DS: Update the given form.
    end

    DS ->> DB: execute_query()
    DB -->> DS: //SQL_CODE//
    DS -->> BE: //label_id, HTTP_CODE//

    alt HTTP_CODE == success
        BE -->> FE: //label_id, 200//
    else
        BE -->> FE: //Database error, HTTP_CODE//
    end

• [ ] POST discard : Remove all transient states of a form.

sequenceDiagram
    title FertiScan Discard Form
    participant C as Client
    participant FE as Frontend
    participant BE as FertiScan
    participant DS as DataStore
    participant DB as SQL

    C ->> FE: discard_form()
    FE ->> BE: POST /discard/label_id
    note over BE: The label_id of the form you want to discard.

    BE ->> DS: discard_form()
    DS ->> DB: execute_query(query)
    DB -->> DS: //SQL_CODE//
    DS -->> BE: //SQL_CODE, HTTP_CODE//

    alt HTTP_CODE == success
        BE -->> FE: //Successfully discarded, 200//
    else
        BE -->> FE: //Database error, 500//
    end

Closes tasks in #82

[snakedye]

So far this PR only contains documentation for commit and discard. Let me your thoughts. @Francois-Werbrouck @Youllou @Endlessflow

[Francois-Werbrouck]

I personally do not like the terminology "commit" since there are no where in the user's interaction where they commit something. They either confirm, validate or send a form with feedback. So commit is a bit confusing.

For the Sequence graph, I'd like to better see the interaction FE - BE - DS. Does the FE gives the user_id to track the form, is it his email? The user_id will be requiered to register an analysis. Will it be within the form or as a parameter?

Btw there wont be queries created to deal with the database. Everything will be dealt with functions from the DS which will be called by the BE depending on the scenario.

It would also be a great bonus if we can differentiate the type of errors, because it wont only be a database error, The DS will return specific error type (user not registered, a requiered field is empty, etc) or an Exception which reprensent an unhandled/un-expected type of error. I know this is far fetched but it is something we on Nachet are trying to improve atm since it's really hard to know what doesn't work on the application if the error management from the FE-BE is not well established with a code ruling. Still, kudos on labeling your errors in the graph this is more than expected 🥇

[Francois-Werbrouck]

I also really advise to use mermaid within markdown because this is a great way to write documentation and also draw graphs in the same document without requiering png to be added to the repo.

[snakedye]

I personally do not like the terminology "commit" since there are no where in the user's interaction where they commit something. They either confirm, validate or send a form with feedback. So commit is a bit confusing.

It's the "sending with feedback" I interpreted as commit. The feedback from his perspective is effectively the changes made to the form. Each time update in the confirmation or confirmation is tied to submission of the form. Maybe "submit" is better since it's in same lexicon as "form".

For the Sequence graph, I'd like to better see the interaction FE - BE - DS. Does the FE gives the user_id to track the form, is it his email? The user_id will be requiered to register an analysis. Will it be within the form or as a parameter?

I implemented the Basic auth scheme. I left the authentication part out from this since I was still unsure about how it would be dealt in the future but we can go with what's already there.

Btw there wont be queries created to deal with the database. Everything will be dealt with functions from the DS which will be called by the BE depending on the scenario.

Thanks, I imagine they are/will be documented in the datastore soon?

I also really advise to use mermaid within markdown because this is a great way to write documentation and also draw graphs in the same document without requiering png to be added to the repo.

I also use the images in the wiki, that's why :/. If we can just link the mermaid file in the wiki it'd be optimal.

I'm taking note of the rest (errors/exceptions, interaction FE - BE - DS, terminoly of endpoints). Thanks for the feedback!

[snakedye]

API Endpoints

Following the meeting with @k-allagbe and @Endlessflow , I came to the conclusion that the API should be refactored because it's doesn't handle well the creation of the form in the database. It would have worked if we limit the user to one form but that's not ideal in the long run.

Workflow

POST /forms

sequenceDiagram
    title FertiScan Create Form
    actor C as Client
    participant FE as Frontend
    participant BE as FertiScan
    participant DS as DataStore
    participant DB as SQL

    C ->> FE: create_form()
    FE ->> BE: POST /forms
    Note right of BE: Authorization: Basic, Content: JSON (Form)
    BE ->> DS: create_form()
    Note right of BE: Creates a new unconfirmed form in the backend for the user.
    DS ->> DB: execute_query()
    DB -->> DS: //SQL_CODE//
    DS -->> BE: //JSON, HTTP_CODE//
    alt HTTP_CODE is success
        BE -->> FE: //JSON, 200//
        Note right of BE: {"message": "...", "form_id": "<form_id>"}
    else
        BE -->> FE: //Database error, HTTP_CODE//
    end

PUT /forms

sequenceDiagram
    title FertiScan Update Form
    actor C as Client
    participant FE as Frontend
    participant BE as FertiScan
    participant DS as DataStore
    participant DB as SQL

    C ->> FE: submit_form()
    FE ->> BE: PUT /forms/form_id
    Note right of BE: Authorization: Basic, Content: JSON (Form)
    alt form.confirm == true
        BE ->> DS: submit_final_form()
        Note left of DS: the final version of the form.
    else
        BE ->> DS: submit_update_form()
        Note left of DS: Update the given form.
    end
    DS ->> DB: execute_query()
    DB -->> DS: //SQL_CODE//
    DS -->> BE: //message, HTTP_CODE//
    alt HTTP_CODE is success
        BE -->> FE: //message, 200//
    else
        BE -->> FE: //Database error, HTTP_CODE//
    end

DELETE /forms

sequenceDiagram
    title FertiScan Discard Form
    actor C as Client
    participant FE as Frontend
    participant BE as FertiScan
    participant DS as DataStore
    participant DB as SQL

    C ->> FE: discard_form()
    FE ->> BE: DELETE /forms/form_id
    BE ->> DS: discard_form()
    DS ->> DB: execute_query(query)
    DS -->> DB: //SQL_CODE//
    DS -->> BE: //message, HTTP_CODE//
    alt HTTP_CODE is success
        BE -->> FE: //Successfully discarded, 200//
    else
        BE -->> FE: //Database error, 500//
    end

[k-allagbe]

@snakedye 👌. For good measure, I suggest adding a GET route. We should not care too much about how the frontend will use the API. Pas besoin de faire du "sur mesure".

Forms, however, sounds a bit vague. It should denote as precisely as possible the entity the user will be manipulating.

[Francois-Werbrouck]

I'd like to point out, the email isn't the user_id. Each user must be registered with their emails and their id is returned. Therefore the BE can operate directly with the user_id instead of the email.

I'm also wondering where and when the pictures are sent over to the Datastore to be saved and linked with the form.

[snakedye]

Thanks for clarifying that @Francois-Werbrouck , I'll remove the mention of the email in the diagrams.

I'm also wondering where and when the pictures are sent over to the Datastore to be saved and linked with the form.

POST /forms and/or PUT /forms.

I was thinking of an object like this:

{
    "confirmed": "false",
    "form": {
    },
    "images": [
    ]
}

Or as send it as form data like with analyze. It'd be the same object but without the "images" key.

This is up to you. Whatever is more convenient for the datastore.