specify file upload

doc/apiv3-documentation.apib

@@ -816,6 +816,77 @@ Permanently deletes the specified attachment.
                 "message": "The specified work package does not exist."
             }
 
+## Add attachment to a work package [POST]
+
+To add an attachment to a work package, a client needs to issue a request of type `multipart/related`
+with exactly two parts.
+
+The first part contains metadata, such as the file name and its description.
+Its content type is expected to be `application/json`, the content must be a single JSON object,
+containing at least the `fileName` and optionally the attachments `description`.
+
+The second part contains the file data, its content type *should* match the mime type of the file
+content.
+
++ Parameters
+    + id (required, integer, `1`) ... ID of the work package to receive the attachment
+
++ Request (multipart/related)
+
+        --boundary-delimiter
+        Content-Type: application/json; charset=UTF-8
+
+        {
+          "fileName": "cute-cat.png",
+          "description": {
+            "raw": "A cute kitty, cuddling with its friends!"
+          }
+        }
+
+        --boundary-delimiter
+        Content-Type: image/png
+
+        PNG file data
+        --boundary-delimiter--
+
++ Response 200 (application/hal+json)
+
+    [Attachment][]
+
++ Response 403 (application/hal+json)
+
+    Returned if the client does not have sufficient permissions.
+
+    **Required permission:** edit work package
+
+    *Note that you will only receive this error, if you are at least allowed to see the work package.*
+
+    + Body
+
+            {
+                "_type": "Error",
+                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
+                "message": "You are not allowed to delete this attachment."
+            }
+
++ Response 404 (application/hal+json)
+
+    Returned if the work package does not exist or the client does not have sufficient permissions
+    to see it.
+
+    **Required permission:** view work package
+
+    *Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
+    That's why a 404 is returned here, even if a 403 might be more appropriate.*
+
+    + Body
+
+            {
+                "_type": "Error",
+                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
+                "message": "The specified work package does not exist."
+            }
+
 # Group Categories
 
 ## Linked Properties