Create endpoint

- new marshmallow schema
- controller function

Author: harminius

server/mergin/sync/files.py

@@ -122,5 +122,5 @@ class ProjectFileSchema(FileSchema):
     def patch_field(self, data, **kwargs):
         # drop 'diff' key entirely if empty or None as clients would expect
         if not data.get("diff"):
-            data.pop("diff")
+            data.pop("diff", None)
         return data

server/mergin/sync/public_api_v2.yaml

@@ -76,6 +76,35 @@ paths:
         "409":
           $ref: "#/components/responses/Conflict"
       x-openapi-router-controller: mergin.sync.public_api_v2_controller
+    get:
+      tags:
+        - project
+      summary: Get project info
+      operationId: get_project
+      parameters:
+        - name: files_at_version
+          in: query
+          description: Include list of files at specific version
+          required: false
+          schema:
+            type: string
+            example: v3
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectDetail"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      x-openapi-router-controller: mergin.sync.public_api_v2_controller
   /projects/{id}/scheduleDelete:
     post:
       tags:
@@ -287,3 +316,80 @@ components:
           $ref: "#/components/schemas/ProjectRole"
         role:
           $ref: "#/components/schemas/Role"
+    ProjectDetail:
+      type: object
+      required:
+        - id
+        - name
+        - workspace
+        - role
+        - version
+        - created_at
+        - updated_at
+        - public
+        - size
+      properties:
+        id:
+          type: string
+          description: project uuid
+          example: c1ae6439-0056-42df-a06d-79cc430dd7df
+        name:
+          type: string
+          example: survey
+        workspace:
+          type: object
+          properties:
+            id:
+              type: integer
+              example: 123
+            name:
+              type: string
+              example: mergin
+        role:
+          $ref: "#/components/schemas/ProjectRole"
+        version:
+          type: string
+          description: latest project version
+          example: v2
+        created_at:
+          type: string
+          format: date-time
+          description: project creation timestamp
+          example: 2025-10-24T08:27:56Z
+        updated_at:
+          type: string
+          format: date-time
+          description: last project update timestamp
+          example: 2025-10-24T08:28:00.279699Z
+        public:
+          type: boolean
+          description: whether the project is public
+          example: false
+        size:
+          type: integer
+          description: project size in bytes for this version
+          example: 17092380
+        files:
+          type: array
+          description: List of files in the project
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: File name including path from project root
+                example: data/layer.gpkg
+              mtime:
+                type: string
+                format: date-time
+                description: File modification timestamp
+                example: 2024-11-19T13:50:00Z
+              size:
+                type: integer
+                description: File size in bytes
+                example: 1234
+              checksum:
+                type: string
+                description: File checksum hash
+                example: 9adb76bf81a34880209040ffe5ee262a090b62ab
+

server/mergin/sync/public_api_v2_controller.py

@@ -8,13 +8,14 @@
 from flask_login import current_user
 
 from mergin.sync.forms import project_name_validation
+from .files import ProjectFileSchema
 
-from .schemas import ProjectMemberSchema
+from .schemas import ProjectMemberSchema, ProjectSchemaV2
 from .workspace import WorkspaceRole
 from ..app import db
 from ..auth import auth_required
 from ..auth.models import User
-from .models import Project, ProjectRole, ProjectMember
+from .models import Project, ProjectRole, ProjectMember, ProjectVersion
 from .permissions import ProjectPermissions, require_project_by_uuid
 
 
@@ -128,3 +129,18 @@ def remove_project_collaborator(id, user_id):
     project.unset_role(user_id)
     db.session.commit()
     return NoContent, 204
+
+
+def get_project(id, files_at_version=None):
+    """Get project info. Include list of files at specific version if requested."""
+    project = require_project_by_uuid(id, ProjectPermissions.Read)
+    data = ProjectSchemaV2().dump(project)
+    if files_at_version:
+        pv = ProjectVersion.query.filter_by(
+            project_id=project.id, name=ProjectVersion.from_v_name(files_at_version)
+        ).first_or_404()
+        data["files"] = ProjectFileSchema(
+            only=("path", "mtime", "size", "checksum"), many=True
+        ).dump(pv.files)
+
+    return data, 200

server/mergin/sync/schemas.py

@@ -405,3 +405,40 @@ class ProjectMemberSchema(Schema):
     project_role = fields.Enum(enum=ProjectRole, by_value=True)
     workspace_role = fields.Enum(enum=WorkspaceRole, by_value=True)
     role = fields.Enum(enum=ProjectRole, by_value=True)
+
+
+class ProjectSchemaV2(ma.SQLAlchemyAutoSchema):
+    id = fields.UUID()
+    name = fields.String()
+    version = fields.Function(lambda obj: ProjectVersion.to_v_name(obj.latest_version))
+    public = fields.Boolean()
+    size = fields.Integer(attribute="disk_usage")
+
+    created_at = DateTimeWithZ(attribute="created")
+    updated_at = DateTimeWithZ(attribute="updated")
+
+    workspace = fields.Function(
+        lambda obj: {"id": obj.workspace.id, "name": obj.workspace.name}
+    )
+    role = fields.Method("_role")
+
+    def _role(self, obj):
+        role = ProjectPermissions.get_user_project_role(obj, current_user)
+        if not role:
+            return None
+        return role.value
+
+    class Meta:
+        model = Project
+        load_instance = True
+        fields = (
+            "id",
+            "name",
+            "version",
+            "public",
+            "size",
+            "created_at",
+            "updated_at",
+            "workspace",
+            "role",
+        )