[#45908] API specification: Add prepare upload endpoint

- https://community.openproject.org/work_packages/45908

docs/api/apiv3/components/schemas/storage_file_upload_link_model.yml

@@ -0,0 +1,32 @@
+# Schema: StorageFileUploadLinkModel
+---
+type: object
+required:
+  - _type
+  - _links
+properties:
+  _type:
+    type: string
+    enum:
+      - UploadLink
+  _links:
+    type: object
+    required:
+      - self
+      - destination
+    properties:
+      self:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              This upload link resource. As the upload link is a temporal object, and cannot be retrieved again, the
+              self link usually is `urn:openproject-org:api:v3:storages:upload_link:no_link_provided`.
+
+              **Resource**: UploadLink
+      destination:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The direct upload link.
+
+              **Resource**: N/A

docs/api/apiv3/components/schemas/storage_file_upload_preparation_model.yml

@@ -0,0 +1,20 @@
+# Schema: StorageFileUploadPreparationModel
+---
+type: object
+required:
+  - projectId
+  - fileName
+  - parent
+properties:
+  projectId:
+    type: integer
+    description: The project identifier, from where a user starts uploading a file.
+    minimum: 1
+  fileName:
+    type: string
+    description: The file name.
+  parent:
+    type: string
+    description: |- 
+      The directory to which the file is to be uploaded. For root directories, the value `/` must
+      be provided.

docs/api/apiv3/components/schemas/time_entry_create_form.yml

@@ -1,2 +0,0 @@
-# Schema: Time_entry_create_form
---- {}

docs/api/apiv3/components/schemas/time_entry_update_form.yml

@@ -1,2 +0,0 @@
-# Schema: Time_entry_update_form
---- {}

docs/api/apiv3/components/schemas/unlock_user.yml

@@ -1,2 +0,0 @@
-# Schema: Unlock_user
---- {}

docs/api/apiv3/components/schemas/update_group.yml

@@ -1,2 +0,0 @@
-# Schema: Update_group
---- {}

docs/api/apiv3/components/schemas/update_user.yml

@@ -1,2 +0,0 @@
-# Schema: Update_User
---- {}

docs/api/apiv3/openapi-spec.yml

@@ -363,6 +363,8 @@ paths:
     "$ref": "./paths/storage.yml"
   "/api/v3/storages/{id}/files":
     "$ref": "./paths/storage_files.yml"
+  "/api/v3/storages/{id}/files/prepare_upload":
+    "$ref": "./paths/storage_files_prepare_upload.yml"
   "/api/v3/storages/{id}/oauth_client_credentials":
     "$ref": "./paths/storage_oauth_client_credentials.yml"
   "/api/v3/time_entries":
@@ -752,6 +754,10 @@ components:
       "$ref": "./components/schemas/storage_file_model.yml"
     StorageFileLocationModel:
       "$ref": "./components/schemas/storage_file_location_model.yml"
+    StorageFileUploadPreparationModel:
+      "$ref": "./components/schemas/storage_file_upload_preparation_model.yml"
+    StorageFileUploadLinkModel:
+      "$ref": "./components/schemas/storage_file_upload_link_model.yml"
     StorageReadModel:
       "$ref": "./components/schemas/storage_read_model.yml"
     StorageWriteModel:
@@ -760,24 +766,14 @@ components:
       "$ref": "./components/schemas/time_entry_model.yml"
     Time_Entry_ActivityModel:
       "$ref": "./components/schemas/time_entry_activity_model.yml"
-    Time_entry_create_form:
-      "$ref": "./components/schemas/time_entry_create_form.yml"
-    Time_entry_update_form:
-      "$ref": "./components/schemas/time_entry_update_form.yml"
     TypeModel:
       "$ref": "./components/schemas/type_model.yml"
     TypesModel:
       "$ref": "./components/schemas/types_model.yml"
     Types_by_ProjectModel:
       "$ref": "./components/schemas/types_by_project_model.yml"
-    Unlock_user:
-      "$ref": "./components/schemas/unlock_user.yml"
     Unstar_QueryModel:
       "$ref": "./components/schemas/unstar_query_model.yml"
-    Update_User:
-      "$ref": "./components/schemas/update_user.yml"
-    Update_group:
-      "$ref": "./components/schemas/update_group.yml"
     UserCollectionModel:
       "$ref": "./components/schemas/user_collection_model.yml"
     UserCreateModel:

docs/api/apiv3/paths/storage.yml

@@ -116,12 +116,10 @@ delete:
         application/hal+json:
           schema:
             $ref: '../components/schemas/error_response.yml'
-          examples:
-            response:
-              value:
-                _type: Error
-                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
-                message: You are not authorized to access this resource.
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
+            message: You are not authorized to access this resource.
       description: |-
         Returned if the client does not have sufficient permissions.
 

docs/api/apiv3/paths/storage_files.yml

@@ -44,6 +44,19 @@ get:
             _type: Error
             errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
             message: The given parent is not a directory.
+    '403':
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
+            message: You are not authorized to access this resource.
+      description: |-
+        Returned if the client does not have sufficient permissions.
+
+        **Required permission:** manage file links
     '404':
       content:
         application/hal+json:

docs/api/apiv3/paths/storage_files_prepare_upload.yml

@@ -0,0 +1,58 @@
+# /api/v3/storages/{id}/files/prepare_upload
+---
+post:
+  summary: Preparation of a direct upload of a file to the given storage.
+  operationId: prepare_storage_file_upload
+  tags:
+    - File links
+  description: |-
+    Executes a request that prepares a link for a direct upload to the storage.
+    
+    The background here is, that the client needs to make a direct request to the storage instance for file uploading,
+    but should not get access to the credentials, which are stored in the backend. The response contains a link object,
+    that enables the client to execute a file upload without the real credentials.
+  parameters:
+    - name: id
+      description: Storage id
+      in: path
+      required: true
+      schema:
+        type: integer
+      example: 1337
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../components/schemas/storage_file_upload_preparation_model.yml'
+  responses:
+    '201':
+      description: OK
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/storage_file_upload_link_model.yml'
+    '400':
+      description: Returned if the given parent parameter value does not refer to a directory.
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
+            message: The given parent is not a directory.
+    '404':
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+            message: The requested resource could not be found.
+      description: |-
+        Returned in either of those cases:
+        - if the storage does not exist or the client does not have sufficient permissions to see it
+
+          **Required permission:** view file links
+        - if the document root file identification does not exist on the storage

modules/storages/lib/api/v3/storage_files/storage_files_api.rb

@@ -48,12 +48,6 @@ module API::V3::StorageFiles
           )
       end
 
-      # RequestBody:
-      # {
-      #   "projectId": 42
-      #   "fileName": "ape.png",
-      #   "parent": "/Pictures"
-      # }
       post :prepare_upload do
         raise ::API::Errors::NotFound unless OpenProject::FeatureDecisions.storage_file_upload_active?