Introduce one endpoint for all review requests: /submissions (#613)

* Move to a generic submission endpoint instead of per-assettype

* Update the reviewing documentation

* Partial progress to reviewing multiple assets

* Allow bundling assets in one review request

* Update review and retract to allow multiple assets

* pre-commit fixes

* Update tests to reflect new usage

* Update documentation

* Add tests for multi-owned assets

* Added migration script

Author: PGijsbers

alembic/alembic/versions/d02aac64a5c7_multi_asset_reviews.py

@@ -0,0 +1,95 @@
+"""multi_asset_reviews
+
+Revision ID: d02aac64a5c7
+Revises: 1fd9b6a162c4
+Create Date: 2025-09-16 12:27:10.238574
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "d02aac64a5c7"
+down_revision: Union[str, None] = "1fd9b6a162c4"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # We use a nuclear approach as there are no reviews in the database anyway:
+    op.drop_table("review")
+    op.drop_table("submission")
+
+    # We could leave it at the above an rely on SQLAlchemy to create the tables below.
+    # However, this increases the complexity of the deployment so make it explicit:
+    op.create_table(
+        "submission",
+        sa.Column("identifier", sa.Integer(), nullable=False, autoincrement=True),
+        sa.Column("request_date", sa.DateTime(), nullable=False),
+        sa.Column("comment", sa.String(256), nullable=False),
+        sa.Column("requestee_identifier", sa.String(255), nullable=True),
+        sa.PrimaryKeyConstraint("identifier"),
+        sa.ForeignKeyConstraint(
+            ["requestee_identifier"],
+            ["user.subject_identifier"],
+            name="submission_ibfk_1",
+            ondelete="SET NULL",
+        ),
+    )
+    op.create_index("requestee_identifier", "submission", ["requestee_identifier"])
+
+    op.create_table(
+        "review",
+        sa.Column("comment", sa.String(1800), nullable=False),
+        sa.Column(
+            "decision",
+            sa.Enum("ACCEPTED", "REJECTED", "RETRACTED", name="review_decision"),
+            nullable=True,
+        ),
+        sa.Column("identifier", sa.Integer(), nullable=False, autoincrement=True),
+        sa.Column("decision_date", sa.DateTime(), nullable=False),
+        sa.Column("reviewer_identifier", sa.String(255), nullable=False),
+        sa.Column("submission_identifier", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("identifier"),
+        sa.ForeignKeyConstraint(
+            ["reviewer_identifier"], ["user.subject_identifier"], name="review_ibfk_1"
+        ),
+        sa.ForeignKeyConstraint(
+            ["submission_identifier"], ["submission.identifier"], name="review_ibfk_2"
+        ),
+    )
+    op.create_index("reviewer_identifier", "review", ["reviewer_identifier"])
+    op.create_index("submission_identifier", "review", ["submission_identifier"])
+
+    op.create_table(
+        "asset_review",
+        sa.Column("asset_identifier", sa.String(255), nullable=False),
+        sa.Column("aiod_entry_identifier", sa.Integer(), nullable=False),
+        sa.Column("review_identifier", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("aiod_entry_identifier", "review_identifier"),
+        sa.ForeignKeyConstraint(
+            ["aiod_entry_identifier"],
+            ["aiod_entry.identifier"],
+            name="asset_review_ibfk_1",
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["review_identifier"],
+            ["submission.identifier"],
+            name="asset_review_ibfk_2",
+            ondelete="CASCADE",
+        ),
+    )
+    op.create_index("review_identifier", "asset_review", ["review_identifier"])
+
+
+def downgrade() -> None:
+    op.drop_table("review")
+    op.drop_table("asset_review")
+    op.drop_table("submission")
+
+    # just start the server and the tables will be created automatically.

docs/using/upload.md

@@ -41,36 +41,37 @@ of the endpoints, including their exact addresses and schemas used.
 The sections below describe the process in more detail.
 
 ### Registering the Asset
-You upload your assets to `/ASSET/v1` using a `POST` request that contains
+You upload your assets to `/ASSET` using a `POST` request that contains
 in the JSON body all the required data for the asset type. A successful response
 should look something like this:
 
 ```json
 {
-  "identifier": 3
+  "identifier": "case_n8DhfFgMYv4beBnVurHa13ZS"
 }
 ```
 
 Take a note of the identifier assigned to the asset, as you will need it to request a review in the next step.
 The asset is now in draft mode, which means that other users cannot see it but you can, and you may still edit it.
-To edit the asset, use the `PUT` endpoints for `/ASSET/v1`.
+To edit the asset, use the `PUT` endpoints for `/ASSET`.
 
 ### Requesting a Review
 When you want to publish the asset, you can submit it for review. You
-can do this by making a `POST` request to the `/ASSET/submit/v1/IDENTIFIER` endpoint.
-Here you need to replace `IDENTIFIER` with the identifier of the asset you retrieved
-in the last step.
-You may include a comment to the reviewer of up to 256 characters in the body of the
+can do this by making a `POST` request to the `/submissions` endpoint.
+You are required to include the identifier in the request body,
+and may include a comment to the reviewer of up to 256 characters in the body of the
 `POST` request, this should generally not be necessary but may be useful to provide
-some clarification:
+some clarification. You may supply more than one asset identifier at once,
+these assets will then be accepted and rejected together.
 
 ```json
 {
+  "asset_identifiers": ["case_n8DhfFgMYv4beBnVurHa13ZS"],
   "comment": "Clarification the reviewer should be aware of."
 }
 ```
 
-When you request a submission, you also get a response with the submission's identifier.
+When you request a submission, you get a response with the submission's identifier.
 
 ```json
 {
@@ -92,44 +93,43 @@ in their review.
 
 You can check that status of your pending submission in two ways.
 First, you can request the status for that review specifically using the
-`/submissions/v1/IDENTIFIER` endpoint, where `IDENTIFIER` needs to replaced with the
+`/submissions/IDENTIFIER` endpoint, where `IDENTIFIER` needs to replaced with the
 identifier of the _submission_ (not the asset!).
 For example, if the submission identifier we received was '1', we can query
-`submissions/v1/1` and retrieve its status which would look something like:
+`submissions/1` and retrieve its status which would look something like:
 ```json
 {
   "comment": "Clarification the reviewer should be aware of.",
   "identifier": 1,
   "request_date": "2025-03-20T09:09:54",
   "aiod_entry_identifier": 212,
-  "asset_type": "case_study",
   "reviews": [],
-  "asset": {
+  "assets": [{
     ...
-  }
+  }]
 }
 ```
 No reviews have yet been performed on the submission, as indicated by the empty list
 of reviews (`"reviews": []`).
 
 Alternatively, you can request an overview of all your submissions with a `GET` request
-to the `submissions/v1` endpoint, which will result in a response such as:
+to the `submissions` endpoint, which will result in a response such as:
 ```json
 [
   {
     "comment": "Clarification the reviewer should be aware of.",
     "identifier": 1,
     "request_date": "2025-03-20T09:09:54",
     "aiod_entry_identifier": 212,
-    "asset_type": "case_study"
+    "asset_identifiers": ["case_n8DhfFgMYv4beBnVurHa13ZS"],
   }
 ]
 ```
 This endpoint fetches and returns minimal information of the submission, which makes it
 more lightweight for creating an overview. However, it does not return the status of the
 submissions directly. Instead, you may use query parameters to request only a subset of
 the submissions, such as those that still require a review (i.e., pending submissions)
-by querying `submissions/v1/?mode=pending`.
+by querying `submissions?mode=pending`.
 Please refer to the endpoint documentation for other options.
 
 Users are only ever able to view information about their own submissions.
@@ -141,22 +141,21 @@ is likely revealing).
 #### Retracting a Submission
 Sometimes you may want to retract a submitted asset before a reviewer manages to review it.
 For example, to correct a mistake in the original submission. You can retract an asset from
-review at any time by doing a `POST` request to the `/submissions/retract/v1/SUBMISSION_IDENTIFIER`
+review at any time by doing a `POST` request to the `/submissions/retract/SUBMISSION_IDENTIFIER`
 endpoint.
 
 A retracted submission is treated the same as a rejected submission. The asset is put back
-into draft status and will not be reviewed until the you submit a new review request.
+into draft status and will not be reviewed until you submit a new review request.
 
 ### A Rejected Submission
-You may find that your submission gets rejected. In that case, the `submissions/v1/IDENTIFIER`
+You may find that your submission gets rejected. In that case, the `submissions/IDENTIFIER`
 endpoint will provide you with the reviewer feedback, e.g.:
 ```json
 {
   "comment": "Clarification the reviewer should be aware of.",
   "identifier": 1,
   "request_date": "2025-03-20T09:09:54",
   "aiod_entry_identifier": 212,
-  "asset_type": "case_study",
   "reviews": [
     {
       "comment": "Several critical fields have incomplete information. Please improve the description, and add a house number to the address.",
@@ -166,11 +165,11 @@ endpoint will provide you with the reviewer feedback, e.g.:
       "submission_identifier": 1
     }
   ],
-  "asset": { ... }
+  "assets": [{ ... }]
 }
 ```
 You'll find reviewer comments under "reviews".
-You may subsequently edit your asset using `PUT` requests to `/ASSET/v1` to address
+You may subsequently edit your asset using `PUT` requests to `/ASSET` to address
 the reviewer feedback, and then request a new review following the regular submission
 process.
 
@@ -182,17 +181,17 @@ The only restriction is that a reviewer cannot review their own submission.
 
 For reviewers, the main endpoints of interest are:
 
-  * `/submissions/v1` to fetch identifiers of submissions which require a review.
+  * `/submissions` to fetch identifiers of submissions which require a review.
 The `?mode=oldest` parameter can be used to fetch the submission which has been waiting for a review the longest.
-  * `/submissions/v1/{identifier}` to get more detailed information on the submission,
+  * `/submissions/{identifier}` to get more detailed information on the submission,
 in particular this will provide also the asset body to review.
   * `/reviews/v1` the endpoint through which reviews can be made using `POST` requests.
 
 Given a submission identifier (obtained from either `/submissions` endpoint mentioned above),
-the review can post a review to `/reviews/v1`. This requires the user to make a decision
+the review can post a review to `/reviews`. This requires the user to make a decision
 to accept or reject the submission, and optionally leave a comment. When rejecting an
 asset, a comment is strongly encouraged, otherwise the user will not know how to improve
-their submission. An example body of the `POST` request to `/reviews/v1` could look like:
+their submission. An example body of the `POST` request to `/reviews` could look like:
 ```json
 {
   "comment": "Several critical fields have incomplete information. Please improve the description, and add a house number to the address.",

src/database/review.py

@@ -3,13 +3,13 @@
 from typing import Any
 
 import sqlalchemy
-from sqlalchemy import Column, select
+from sqlalchemy import Column
 from sqlmodel import SQLModel, Field, Relationship, Session
 
 from database.model.field_length import NORMAL, LONG
 from database.model.concept.concept import AIoDConcept
 from database.model.helper_functions import non_abstract_subclasses
-from routers.helper_functions import get_all_asset_schemas
+from routers.helper_functions import get_all_asset_schemas, get_asset_type_by_abbreviation
 
 REQUIRED_NUMBER_OF_REVIEWS = 1
 
@@ -53,9 +53,25 @@ class Review(ReviewBase, table=True):  # type: ignore [call-arg]
     submission: "Submission" = Relationship(back_populates="reviews")
 
 
+class SubmissionCreateV2(SQLModel):
+    """User provided information to submit a review request."""
+
+    comment: str = Field(
+        description="Optional. Comment to the reviewer to motivate the submission or provide clarification.",
+        max_length=NORMAL,
+        default="",
+        schema_extra={"example": "'IA' is not a typo, it's for L'intelligence artificielle."},
+    )
+
+
 class SubmissionCreate(SQLModel):
     """User provided information to submit a review request."""
 
+    asset_identifiers: list[str] = Field(
+        description="List of identifiers of the assets to submit for review",
+        min_length=1,
+        schema_extra={"example": ["case_n8DhfFgMYv4beBnVurHa13ZS"]},
+    )
     comment: str = Field(
         description="Optional. Comment to the reviewer to motivate the submission or provide clarification.",
         max_length=NORMAL,
@@ -64,17 +80,29 @@ class SubmissionCreate(SQLModel):
     )
 
 
-class SubmissionBase(SubmissionCreate):
+class SubmissionBase(SQLModel):
     """A review request, requested by a user to publish an asset/change."""
 
     identifier: int = Field(primary_key=True, default=None)
     request_date: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    comment: str = Field(
+        description="Optional. Comment to the reviewer to motivate the submission or provide clarification.",
+        max_length=NORMAL,
+        default="",
+        schema_extra={"example": "'IA' is not a typo, it's for L'intelligence artificielle."},
+    )
 
+
+class AssetReview(SQLModel, table=True):  # type: ignore[call-arg]
+    __tablename__ = "asset_review"
+    asset_identifier: str = Field()
     # If the entry corresponding to the thing it reviews is removed,
     # then we also want to permanently remove the review data.
-    aiod_entry_identifier: int = Field(foreign_key="aiod_entry.identifier", ondelete="CASCADE")
-    asset_type: str = Field(
-        description="The name of the table of the resource. E.g. 'dataset' or 'person'"
+    aiod_entry_identifier: int = Field(
+        primary_key=True, nullable=False, foreign_key="aiod_entry.identifier", ondelete="CASCADE"
+    )
+    review_identifier: int = Field(
+        primary_key=True, nullable=False, foreign_key="submission.identifier", ondelete="CASCADE"
     )
 
 
@@ -88,20 +116,25 @@ class Submission(SubmissionBase, table=True):  # type: ignore [call-arg]
     )
 
     reviews: list[Review] = Relationship(back_populates="submission")
+    _assets: list[AssetReview] = Relationship()
 
     @property
-    def asset(self) -> AIoDConcept:
+    def assets(self) -> list[AIoDConcept]:
         # I could not find a way to just use a Relationship directly on account of it needing
         # to be defined on creation but the asset_type is only known at runtime.
         # We still mimic the behavior of a lazy-loaded relationship by fetching the session
         # related to the object, instead of instantiating a new session.
         session = Session.object_session(self)
         available_schemas: list[AIoDConcept] = list(non_abstract_subclasses(AIoDConcept))
         schema_by_name = {schema.__tablename__: schema for schema in available_schemas}
-        schema = schema_by_name[self.asset_type]
 
-        query = select(schema).where(schema.aiod_entry_identifier == self.aiod_entry_identifier)
-        return session.scalars(query).one()
+        assets = []
+        for identifier in [a.asset_identifier for a in self._assets]:
+            prefix, _ = identifier.split("_")
+            asset_type = get_asset_type_by_abbreviation()[prefix]
+            schema = schema_by_name[asset_type.__tablename__]
+            assets.append(session.get(schema, identifier))
+        return assets
 
     @property
     def is_pending(self):
@@ -114,16 +147,20 @@ class SubmissionView(SubmissionBase):
     # only return AIoDConcept fields to the user, instead of all supplied attributes.
     # E.g., a publication's issn is now returned but would not if it was AIoDConcept.
     # Instead we use the configuration below to set the schema annotations.
-    asset: Any = Field()
+    assets: Any = Field()
 
     class Config:
         # This allows us to set the schema generation at runtime, which is necessary since the
         # ResourceRead classes are only defined at runtime (generated dynamically).
         @staticmethod
         def schema_extra(schema: dict[str, Any], _: type["SubmissionView"]) -> None:
-            schema["properties"]["asset"] = {
-                "title": "Asset under review",
-                "description": "The type of the object can be found in SubmissionView.asset_type.",
-                "type": "object",
-                "anyOf": get_all_asset_schemas(),
+            schema["properties"]["assets"] = {
+                "type": "array",
+                "title": "Assets under review",
+                "items": {
+                    "title": "Asset",
+                    "description": "The type of the object can be derived from its identifier.",
+                    "type": "object",
+                    "anyOf": get_all_asset_schemas(),
+                },
             }