New endpoint POST /delete/studies for batch study deletion

[GuilhemSempere]

Summary

Add a new endpoint to the BrAPI Core specification for batch deletion of studies, following the exact pattern of POST /delete/images.

Motivation

• Allow BrAPI clients to delete one or more studies programmatically
• Provide a standardized deletion interface for platforms like Gigwa to expose their existing study deletion functionality
• Maintain consistency with the existing deletion pattern (/delete/images)

Endpoint Definition

Path: POST /delete/studies

Request Body:

{
  "studyDbIds": ["study1", "study2", "study3"]
}

Parameter	Type	Required	Description
studyDbIds	array[string]	Yes	List of study identifiers to delete

Response (200 OK):

{
  "@context": ["https://brapi.org/jsonld/context/metadata.jsonld"],
  "metadata": {},
  "result": {
    "deletedStudies": [
      { "studyDbId": "study1", "success": true, "message": "Study deleted successfully." },
      { "studyDbId": "study2", "success": false, "message": "Study not found." },
      { "studyDbId": "study3", "success": false, "message": "Cannot delete: study has associated observation units." }
    ]
  }
}

Field	Type	Description
result.deletedStudies	array[object]	Results for each requested deletion
.studyDbId	string	Study identifier from request
.success	boolean	Whether deletion succeeded
.message	string	Human-readable status or error reason

Status Codes:

• 200: Request processed (check individual success flags)
• 400: Malformed request body
• 401: Authentication required
• 403: Insufficient permissions
• 500: Server error

Design Decisions

Pattern Consistency: Follows POST /delete/images exactly:

• Path: /delete/studies
• Request field: studyDbIds
• Response field: deletedStudies

Dependency Handling: Specification does not mandate cascading deletion. Implementations decide validation rules (e.g., block deletion if observation units exist).

Operation Characteristics:

• Synchronous (deletion results embedded in the response)
• Not idempotent (second request returns "not found")
• Batch processing with per-item reporting

Security: The endpoint must enforce appropriate authorization to ensure only permitted users can delete studies. Implementations should verify the requesting user has the necessary permissions for each study before deletion.

[GuilhemSempere]

Amendment: Add study deletion endpoint with search criteria support

Add POST /delete/studies endpoint supporting deletion by studyDbIds, studyNames (with programDbIds/trialDbIds), programDbIds, and trialDbIds.

Request Body

{
  "studyDbIds": ["module§1", "module§2"],
  "programDbIds": ["module1", "module2"],
  "trialDbIds": ["module1", "module2"],
  "studyNames": ["Study A", "Study B"]
}

At least one of studyDbIds or studyNames required. studyNames requires programDbIds or trialDbIds.

Response (200 OK)

{
  "@context": ["https://brapi.org/jsonld/context/metadata.jsonld"],
  "metadata": {
    "pagination": { "pageSize": 2, "currentPage": 0, "totalCount": 2, "totalPages": 1 },
    "status": [
      { "message": "Deleted 1 studies. 1 had insufficient permissions.", "messageType": "WARNING" }
    ]
  },
  "result": {
    "data": [
      {
        "studyDbId": "module§1",
        "additionalInfo": { "success": "true", "message": "Study deleted successfully." }
      },
      {
        "studyDbId": "module§2",
        "additionalInfo": { "success": "false", "message": "Insufficient permissions." }
      }
    ]
  }
}

Behavior

Filters	Result
programDbIds only	All projects in those databases
programDbIds + studyNames	Projects matching both
studyDbIds + studyNames	Projects matching both (AND)
studyNames only	Rejected (needs program/trial)

Design

• Follows POST /delete/images pattern
• Uses POST method (batch operation)
• Uses StudySearchRequest for filters
• Per-item additionalInfo with success and message
• Returns 200 with details even when some deletions fail
• Authentication required; permissions checked per study

Open Questions

1. How should implementations handle multiple studies with the same studyName across different databases or contexts? Should deletion apply to all matching studies, or should servers require additional disambiguation?