challenges with the REST API

[mdagit]

Hi -

I've been hacking together a frontend utility for a research study which uses the unbiased REST backend.
Just FYI some challenges I've had to confront:

• i just now saw that there is OpenAPI documentation. I wished I'd known that -- it isn't advertised, and apparently only available at runtime under the obscure /docs/ path.
• weird asymmetrical types for POST and GET. For example to create a study I have a "covariates" key, and then later when I query it with GET i get back something with a "strata" key.
• strangeness with study object key called "method". I supply a value "var" when I POST a study object to the "minimisation_pocock" path, then later on when I GET, it comes back as value "minimisation_pocock". Maybe it shouldn't even be supplied for the POST -- I'm just copying R test code.
• the GET "/study" request fails; we have to know to have a trailing "/" as GET "/study/"
• There seems to be no way to delete a patient record or study record
• I can supply a study identifier but I can't supply a patient identifier. So there is no server-side assistance in patient uniqueness.
• The patient_stratum database table seems totally unused by the REST API. On a related note, the /study/:study_id/patient POST method is very inconvenient to use, because I have to supply the entire history of all past patient covariate values, even though unbiased already knows this info in its database (or it would, if it actually used the table). Furthermore, when I do a GET /study/:study_id/patient, the data that comes back lacks any covariate info, so I can't fetch it from the system either. I just have to somehow know it through some external means.

All that said, the code quality seems high, and the docker-compose setup was totally seamless.

[kamilsi]

Hi @mdagit,

Thank you so much for taking the time to provide such detailed feedback! We truly appreciate your trust in using the project and the effort you put into outlining the challenges you’ve faced. Your insights will help us improve, and we’ll carefully analyze each of your points to address them appropriately. We will create issues based on your feedback in the coming days.

Kamil

[mdagit]

Oh and another type inconsistency: GET /randomization_list returns an object with key 'arm' while POST /patient returns an object with key 'arm_name' -- while the input current_state to POST /patient expects 'arm' !

I'm programming in TypeScript (which has sort-of opt-in type safety), so having these needless variations makes the API awkward.

Since R is not a type-safe language the code didn't have a strict upbringing :)