feat: add a "transaction" route

cubicweb_api/exceptions.py

@@ -7,6 +7,7 @@
 from yams import ValidationError, UnknownType
 
 from cubicweb_api.httperrors import get_http_error, get_http_500_error
+from cubicweb_api.transaction import InvalidTransaction
 
 log = logging.getLogger(__name__)
 
@@ -24,7 +25,7 @@
     # RQL errors -> 400
     if isinstance(
         wrapped_exception,
-        (ValidationError, QueryError, UnknownType, RQLException),
+        (ValidationError, QueryError, UnknownType, RQLException, InvalidTransaction),
     ):
         return get_http_error(
             400,

cubicweb_api/openapi/openapi_template.yaml

@@ -26,6 +26,7 @@
     post:
       description: Executes the given RQL query
       requestBody:
+        required: true
         content:
           application/json:
             schema:
@@ -36,18 +37,10 @@
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  type: array
-                  items:
-                    oneOf:
-                      - type: 'string'
-                        nullable: true
-                      - type: 'number'
-                      - type: 'boolean'
+                $ref: '#/components/schemas/ResultSet'
         '400':
           description: The given RQL was badly formatted
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorSchema'
@@ -48,9 +41,30 @@
         '400':
           description: The given RQL was badly formatted
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorSchema'
+  /transaction:
+    x-pyramid-route-name: transaction
+    post:
+      description: Execute several queries in a single transaction
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: '#/components/schemas/RqlTransactionParams'
+      responses:
+        '200':
+          description: This instance's Schema
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ResultSet'
   /login:
     x-pyramid-route-name: login
     post:
@@ -135,6 +149,6 @@
           type: object
           default: {}
           additionalProperties:
-            nullable: true
+            $ref: '#/components/schemas/RqlParamsValue'
       required:
         - query
@@ -139,5 +153,39 @@
       required:
         - query
+    RqlParamsValue:
+      oneOf:
+        - type: string
+          nullable: true
+        - type: number
+        - type: boolean
+    RqlTransactionParams:
+      type: object
+      properties:
+        query:
+          type: string
+          minLength: 1
+        params:
+          type: object
+          default: {}
+          additionalProperties:
+            $ref: '#/components/schemas/RqlTransactionParamsValue'
+      required:
+        - query
+    RqlTransactionParamsValue:
+      oneOf:
+        - type: string
+          nullable: true
+        - type: number
+        - type: boolean
+        - type: object
+          properties:
+            queryIndex:
+              type: number
+            row:
+              type: number
+            column:
+              type: number
+          additionalProperties: false
     LoginParams:
       type: object
       properties:
@@ -173,6 +221,16 @@
         - code
         - title
         - error
+    ResultSet:
+      type: array
+      items:
+        type: array
+        items:
+          oneOf:
+            - type: 'string'
+              nullable: true
+            - type: 'number'
+            - type: 'boolean'
     CurrentUser:
       type: object
       nullable: true

cubicweb_api/routes.py

@@ -30,6 +30,7 @@
 )
 from cubicweb_api.openapi.openapi import setup_openapi
 from cubicweb_api.util import get_cw_repo
+from cubicweb_api.transaction import Transaction
 
 log = logging.getLogger(__name__)
 
@@ -41,6 +42,7 @@
 
     schema = "schema"
     rql = "rql"
+    transaction = "transaction"
     login = "login"
     current_user = "current_user"
     help = "help"
@@ -48,8 +50,8 @@
 
 def get_route_name(route_name: ApiRoutes) -> str:
     """
-    Generates a unique route name using the api prefix to prevent clashes with routes
-    from other cubes.
+    Generates a unique route name using the api
+    prefix to prevent clashes with routes from other cubes.
 
     :param route_name: The route name base
     :return: The generated route name
@@ -75,7 +77,8 @@
     )
     def schema_route(self):
         """
-        See the openapi/openapi_template.yml file for more information on this route.
+        See the openapi/openapi_template.yml
+        file for more information about this route.
         """
         repo = get_cw_repo(self.request)
         exporter = JSONSchemaExporter()
@@ -85,7 +88,8 @@
     @view_config(route_name=get_route_name(ApiRoutes.rql), anonymous_or_connected=True)
     def rql_route(self):
         """
-        See the openapi/openapi_template.yml file for more information on this route.
+        See the openapi/openapi_template.yml
+        file for more information about this route.
         """
         request_params = self.request.openapi_validated.body
         query: str = request_params["query"]
@@ -95,7 +99,22 @@
         return rset
 
     @view_config(
+        route_name=get_route_name(ApiRoutes.transaction),
+        request_method="POST",
+        anonymous_or_connected=True,
+    )
+    def transaction_view(self):
+        """
+        See the openapi/openapi_template.yml
+        file for more information about this route.
+        """
+        queries = self.request.openapi_validated.body
+        transaction = Transaction(queries)
+        rsets = [rset.rows for rset in transaction.execute(self.request.cw_cnx)]
+        return rsets
+
+    @view_config(
         route_name=get_route_name(ApiRoutes.login),
     )
     def login_route(self):
         """
@@ -98,8 +117,9 @@
         route_name=get_route_name(ApiRoutes.login),
     )
     def login_route(self):
         """
-        See the openapi/openapi_template.yml file for more information on this route.
+        See the openapi/openapi_template.yml
+        file for more information about this route.
         """
         request_params = self.request.openapi_validated.body
         login: str = request_params["login"]
@@ -125,7 +145,8 @@
     )
     def current_user(self):
         """
-        See the openapi/openapi_template.yml file for more information on this route.
+        See the openapi/openapi_template.yml
+        file for more information about this route.
         """
         user = self.request.cw_cnx.user
         return {"eid": user.eid, "login": user.login, "dcTitle": user.dc_title()}

test/test_api.py

@@ -122,6 +122,94 @@
             "title": "Unauthorized",
         }
 
+    def test_200_on_transaction_when_authenticated(self):
+        self.webapp.post(
+            f"{BASE_URL[:-1]}{API_PATH_DEFAULT_PREFIX}/v1/login",
+            params=json.dumps({"login": self.admlogin, "password": self.admpassword}),
+            content_type="application/json",
+            status=204,
+        )
+
+        queries = [
+            {
+                "query": "INSERT CWUser U: U login %(login)s, U upassword 'AZJEJAZO'",
+                "params": {"login": "ginger"},
+            },
+            {
+                "query": "INSERT CWGroup G: G name %(name)s",
+                "params": {"name": "chickens"},
+            },
+            {
+                "query": "SET U in_group G WHERE U eid %(ginger_eid)s, G eid %(chickens_eid)s",
+                "params": {
+                    "ginger_eid": {"queryIndex": 0, "row": 0, "column": 0},
+                    "chickens_eid": {"queryIndex": 1, "row": 0, "column": 0},
+                },
+            },
+        ]
+        response = self.webapp.post(
+            f"{BASE_URL[:-1]}{API_PATH_DEFAULT_PREFIX}/v1/transaction",
+            params=json.dumps(queries),
+            content_type="application/json",
+            status=200,
+        ).json
+
+        assert len(response) == 3
+        assert isinstance(response[0][0][0], int)
+        assert isinstance(response[1][0][0], int)
+        assert isinstance(response[2][0][0], int)
+        assert isinstance(response[2][0][1], int)
+
+    def test_400_on_invalid_transactions(self):
+        queries = [
+            {
+                "query": "INSERT CWUser U: U login %(login)s, U upassword 'AZJEJAZO'",
+                "params": {"login": {"queryIndex": 0, "row": 0, "column": 0}},
+            },
+        ]
+        response = self.webapp.post(
+            f"{BASE_URL[:-1]}{API_PATH_DEFAULT_PREFIX}/v1/transaction",
+            params=json.dumps(queries),
+            content_type="application/json",
+            status=400,
+        ).json
+
+        assert response == {
+            "message": "A query reference index refers to a request which has not yet "
+            "been executed",
+            "data": None,
+            "title": "InvalidTransaction",
+        }
+
+    def test_400_on_invalid_transactions_query_index(self):
+        queries = [
+            {
+                "query": "INSERT CWUser U: U login %(login)s, U upassword 'AZJEJAZO'",
+                "params": {
+                    "login": {"queryIndex": "not a number", "row": 0, "column": 0}
+                },
+            },
+        ]
+        response = self.webapp.post(
+            f"{BASE_URL[:-1]}{API_PATH_DEFAULT_PREFIX}/v1/transaction",
+            params=json.dumps(queries),
+            content_type="application/json",
+            status=400,
+        ).json
+
+        assert response == {
+            "data": [
+                {
+                    "exception": "ValidationError",
+                    "message": "{'queryIndex': 'not a number', 'row': 0, 'column': 0} is not "
+                    "valid under any of the given schemas",
+                }
+            ],
+            "message": "Your request could not be validated against the openapi "
+            "specification.",
+            "title": "OpenApiValidationError",
+        }
+
     def test_successful_login_returns_204(self):
         self.webapp.post(
             f"{BASE_URL[:-1]}{API_PATH_DEFAULT_PREFIX}/v1/login",