Endpoint structure

[kamilsi]

How to implement general architecture for the endpoint? Initial proposal:

1. Learn about available algorithms and their requirements (GET /randomization_methods)
   • Input: none
   • Output: JSON with available methods and expected request for them

   {
     "shared_parameters": [
       {
         "param_name": "study_id",
         "required": true,
         "data_type": "string",
         "description": "Unique identifier for the study.",
         "example": "RARE-TS"
       },
       {
         "param_name": "number_of_arms",
         "required": true,
         "data_type": "integer",
         "description": "The number of treatment arms in the study."
       }
       // ... other shared parameters
     ],
     "randomization_methods": [
       {
         "method_name": "block",
         "description": "Randomizes subjects into groups ensuring equal group sizes within each block.",
         "parameters": [
           {
             "param_name": "block_size",
             "required": true,
             "data_type": "array",
             "description": "Used sizes of blocks in the randomization process."
           }
           // ... other parameters specific to block randomization
         ]
       },
       {
         "method_name": "dynamic",
         "description": "Randomizes subjects using adaptive methods based on accumulating data.",
         "parameters": [
           {
             "param_name": "minimization_factors",
             "required": true,
             "data_type": "array",
             "description": "List of factors used for minimization, e.g., age, disease stage."
           }
           // ... other parameters specific to dynamic randomization
         ]
       }
       // ... other randomization methods
     ]
   }

2. Initialize Study (POST /study):
   • Inputs:
     • Study identifier
     • Study characteristics (e.g., number of arms)
     • Chosed methods of randomization
     • Specific parameters of chosen method od randomization
   • Outputs:
     • Confirmation of study creation
     • Assigned study metadata (e.g. study_id, timestamp)
3. Get all available studies (GET /study)
   • Input: none
   • Output: list of studies with study_id, names, timestamps
4. Get study details (GET /study/{study_id})
   • Inputs: study_id
   • Outputs:
     • study details (study_id, timestamp)
     • randomization configuration (arms, method, configuration details) including required inputs for randomizing a patient
5. Randomize Patient (POST /study/{study_id}/patient):
   • Inputs:
     • Required patient data
     • Study state required in case of dynamic randomization
   • Outputs:
     • Assigned treatment group
     • Randomization details (e.g., time of randomization)
6. Get randomization list (GET /study/{study_id}/randomization_list):
   • Inputs: none
   • Output:
     • Returns 4xx if dynamic
     • returns randomization list if available
7. Audit Trial of Study (GET /study/{study_id}/audit_trial):
   • Outputs:
     • Randomization log summary: all requests for given study listed with timestamps and replies
8. Delete Study (DELETE /study/{study_id}):
   • Input: none
   • Output: confirmation of study deletion with id, timestamp

[kamilsi]

This is the SQL schema we could use:

CREATE TABLE studies (
    study_id SERIAL PRIMARY KEY,
    study_identifier VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    study_title VARCHAR(255),
    randomization_method VARCHAR(100),
    randomization_parameters JSONB,
    is_active BOOLEAN DEFAULT TRUE,
    deactivated_at TIMESTAMP WITH TIME ZONE
);

CREATE TABLE study_arms (
    arm_id SERIAL PRIMARY KEY,
    study_id INTEGER REFERENCES Studies(study_id),
    arm_label VARCHAR(255)
);

CREATE TABLE patients (
    patient_id SERIAL PRIMARY KEY,
    study_id INTEGER REFERENCES Studies(study_id),
    arm_id INTEGER REFERENCES StudyArms(arm_id),
    randomization_code VARCHAR(255) NOT NULL,
    randomization_code_used BOOLEAN NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, -- Timestamp of the last update
    enrollment_date TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE audit_trail (
    request_id SERIAL PRIMARY KEY,
    request_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    request_endpoint VARCHAR(100),
    request_payload JSONB,
    study_id INTEGER REFERENCES Studies(study_id),
    response_code INTEGER,
    response_payload JSONB
);

CREATE OR REPLACE FUNCTION update_modified_column()
RETURNS TRIGGER AS $$
BEGIN
   NEW.updated_at = CURRENT_TIMESTAMP;
   RETURN NEW;   
END;
$$ language 'plpgsql';

CREATE TRIGGER update_studies_modtime
BEFORE UPDATE ON studies
FOR EACH ROW
EXECUTE FUNCTION update_modified_column();

CREATE TRIGGER update_patients_modtime
BEFORE UPDATE ON patients
FOR EACH ROW
EXECUTE FUNCTION update_modified_column();

[kamilsi]

Following our recent discussion on the design of the randomization algorithm's endpoints, I wanted to provide an update and outline our agreed approach.

As we've determined, the OpenAPI standard doesn't offer a straightforward way to handle conditional parameters for different randomization methods. To ensure clarity and ease of use for our API users, we've decided to create distinct endpoints for each randomization method. This design choice will allow us to provide clear, fixed parameters for each method, which will be thoroughly documented.

Here's a summary of the changes and how they will be implemented:

1. Individual Endpoints for Each Method: Each randomization method (e.g., block, dynamic) will have its own dedicated endpoint. This approach simplifies the API structure and makes it more intuitive for users to understand and implement the right method for their needs.
2. Documentation and Parameters: The documentation will clearly specify the parameters required for each method. We'll include examples and detailed descriptions to facilitate ease of understanding and usage.
3. Shared Parameters: Certain parameters that are common across all methods, such as study_id and number_of_arms, will be consistently used. This ensures a uniform approach while accommodating the specificities of each method.

Endpoints Overview:

1. Initialize Study (POST /study): This will remain largely the same but will now specify which randomization method endpoint to use.
2. Randomize Patient (POST /study/{study_id}/patient): This will be tailored to the chosen randomization method, ensuring that all required data for that specific method is provided.
3. Other Endpoints (GET /study, GET /study/{study_id}, etc.): These will continue to provide general study information and functionalities like study creation, deletion, and audit trials.

We believe that this structured approach will enhance the usability of our API, making it more accessible and easier to integrate for our users. The clarity in documentation and endpoint design will also aid in reducing potential errors and misunderstandings.