diff --git a/marketplace/eqp/v1/files.md b/marketplace/eqp/v1/files.md index d6ecf6f147b..827e04a30e6 100644 --- a/marketplace/eqp/v1/files.md +++ b/marketplace/eqp/v1/files.md @@ -5,17 +5,19 @@ title: Files Use `files` resources to manage all code artifacts and assets associated with an extension or a theme: -* Magento 1 tarball (.tgz) -* Magento 2 ZIP files -* Image files for logos and galleries -* Product Icons -* PDF documents for User Guides, Installation Guides, and Reference Guides +- Magento 1 tarball (.tgz) +- Magento 2 ZIP files +- Image files for logos and galleries +- Product Icons +- PDF documents for User Guides, Installation Guides, and Reference Guides Each file upload receives a unique ID. You must associate these IDs with your submission later using the [packages API](packages.html). -You can associate a file with multiple products. This allows for asset sharing across different packages. For example, you can share an image file for a gallery with different packages by associating it with the same file upload ID. +You can associate a file with multiple products. This allows for asset sharing across different packages. +For example, you can share an image file for a gallery with different packages by associating it with the same file upload ID. -All files that you upload are inspected for malware. We only accept packages if all of its associated files have passed the malware inspection. +All files that you upload are inspected for malware. +We only accept packages for further review if all associated files have passed the malware inspection. ## File uploads @@ -24,7 +26,6 @@ Use this API to upload files, retrieve file upload status, and remove files. ```http GET /rest/v1/files/uploads/:file_upload_id POST /rest/v1/files/uploads -DELETE /rest/v1/files/uploads/:file_upload_id ``` ### Get a file upload @@ -35,6 +36,19 @@ Use the upload ID to retrieve details about a file upload. GET /rest/v1/files/uploads/:file_upload_id ``` +**Parameters** + +|Field|Type|Description| +|-----|----|-----------| +|file_upload_id|URL element|The `file_upload_id` string that was returned when uploading or listing the file.| +|offset|int|The `file_upload_id` string that was returned when uploading or listing the file.| +|limit|int|The `file_upload_id` string that was returned when uploading or listing the file.| + +Sorting and filtering parameters are currently not available for this endpoint. + +If the `file_upload_id` parameter is specified, a single file record will be returned. +If it is omitted, then a batch response will be returned: an array of records for all files uploaded by the current user. + **Request** ```bash @@ -48,55 +62,60 @@ curl -X GET \ ```json { "file_upload_id" : "dhsiXjdksW17623", - "filename" : “acme_one-click-checkout.zip”, + "filename" : "acme_one-click-checkout.zip", "content_type" : "application/zip", "size" : 182934, - "malware_status" : "pass’, - “file_hash” : “f53f5db985b8815f1ce6fd4b48a0439a”, - “submission_ids” : [ + "malware_status" : "pass", + "file_hash" : "f53f5db985b8815f1ce6fd4b48a0439a", + "submission_ids" : [ ], - “is_profile_image” : false + "is_profile_image" : false, + "url" : "https://static-mp.magento.com/user/45/23//pub/1c/ee//icon.png" } ``` -Details on the response fields: +Response field details: |Field|Type|Description| |-----|----|-----------| +|file_upload_id|string|Unique identifier for the file| |filename|string|The name of the file sent in the request.| -|content-type|string|The mime-type of the uploaded file.| +|content_type|string|The mime-type for which the file was uploaded.| |size|integer|The size of the file in bytes.| -|malware_status|string|Indicates the malware check result for this file. Valid values include `pass`, `fail`, and, `in-progress`.| -|file_hash|string|Hash of the file; currently using md5.| -|submission_ids|array|The list of package submissions associated with this file.| -{:.style="table-layout: auto;"} +|malware_status|string|Malware check result for this file. Valid values include: `pass`, `fail`, `in-progress`.| +|file_hash|string|Hash of the file; currently md5. Only set if malware_status is `pass`.| +|url|string|The URL from which the file may be downloaded, if applicable.| +|submission_ids|array|The list of package submissions associated with this file, if any.| + +The order of fields may differ, and additional fields may also be returned. ### Upload files -You upload files in bulk upload using the **multipart/form-data** encoding type. With this approach, binary files can be uploaded without the need for additional encoding, which can result in an increase in overall upload size. +Upload files in bulk using the **multipart/form-data** encoding type. +With this approach, binary files can be uploaded without the need for additional encoding, which could otherwise result in an increase in overall upload size. ```http POST /rest/v1/files/uploads ``` -A sample request body of mime type, [multipart/form-data](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2) with a boundary string of `----------287032381131322` -is shown below: +A sample request body of mime type, [multipart/form-data](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2) +with a boundary string of `----------287032381131322` is shown below: ```text ------------287032381131322 -Content-Disposition: form-data; name="file[]"; filename=“acme_one-click-checkout.zip" +Content-Disposition: form-data; name="file[]"; filename="acme_one-click-checkout.zip" Content-Type: application/zip ------------287032381131322 -Content-Disposition: form-data; name="file[]"; filename=“one-click-icon.png" +Content-Disposition: form-data; name="file[]"; filename="one-click-icon.png" Content-Type: image/png ------------287032381131322 -Content-Disposition: form-data; name="file[]"; filename=“acme-logo.png" +Content-Disposition: form-data; name="file[]"; filename="acme-logo.png" Content-Type: image/png @@ -110,16 +129,22 @@ Content-Type: application/pdf ------------287032381131322-- ``` -* Each part has a header and body with `Content-Disposition` header always set to `form-data`. -* The `name` value must be set to `file[]` for all parts. -* The original filename must be supplied in the `filename` parameter. -* The `Content-Type` header must be set to the appropriate mime-type for the file. -* The body of each part is the full contents of the raw file. +- Each part has a header and body. +- The body of each part is the full contents of the raw file. +- The header has the following required elements: -For example, if you save the previous request body is saved to a temporary file at `/tmp/files-payload`, you can use it in your POST request to upload the file: +|Element|Type|Description| +|-----|--------|-----------| +|Content-Disposition|string|MUST be `form-data`| +|name|string|MUST be `file[]` for all parts.| +|filename|string|Should be the original name of the file.| +|Content-Type|string|Should be the correct mime-type for the file.| **Request** +If the request body given above was saved into a temporary file at `/tmp/files-payload`, +you may use it in your POST request to upload the files: + ```bash curl -X POST \ -H 'Authorization: Bearer baGXoStRuR9VCDFQGZNzgNqbqu5WUwlr.cAxZJ9m22Le7' \ @@ -130,34 +155,36 @@ curl -X POST \ **Response** +The above request gives an output similar to: + ```json [ { - "filename" : “acme_one-click-checkout.zip”, + "filename" : "acme_one-click-checkout.zip", "content_type" : "application/zip", "size" : 182934, - "file_upload_id" : “dhsiXjdksW17623” + "file_upload_id" : "dhsiXjdksW17623" }, { - "filename" : “one-click-icon.png”, + "filename" : "one-click-icon.png", "content_type" : "image/png", "size" : 37492, - "file_upload_id" : “gAdh628bzXv” + "file_upload_id" : "gAdh628bzXv" }, { - "filename" : “acme-logo.png”, + "filename" : "acme-logo.png", "content_type" : "image/png", "size" : 6825, - "file_upload_id" : “fur7284XcgdcV” + "file_upload_id" : "fur7284XcgdcV" }, { - "filename" : “user.pdf”, + "filename" : "user.pdf", "content_type" : "application/pdf", "size" : 48392, - "file_upload_id" : “j47dVbsFgkl” + "file_upload_id" : "j47dVbsFgkl" } ] ``` @@ -173,58 +200,5 @@ Each record in the list has the following fields: |content-type|string|The mime-type of the uploaded file.| |size|integer|The size of the file in bytes.| |file_upload_id|string|A unique identifier for the file.| -{:.style="table-layout: auto;"} The `file_upload_id` must be tracked for subsequent package submission APIs. - -### Delete an uploaded file - -You can only dissociate files from packages that have not been published on the Magento Marketplace. Removing a file without the optional `submission_ids` parameter disassociates it from all linked packages. If no packages are associated with a file, it will be removed. - -```http -DELETE /rest/v1/files/uploads/:file_upload_id -``` - -Available parameters: - -|Parameter|Type|Required|Description| -|---------|----|--------|-----------| -|submission_ids|array|no|A list of submission IDs to disassociate the file from the specified package.| -{:.style="table-layout: auto;"} - -**Request** - -```bash -curl -X DELETE \ - -H 'Authorization: Bearer baGXoStRuR9VCDFQGZNzgNqbqu5WUwlr.cAxZJ9m22Le7' \ - https://developer-api.magento.com/rest/v1/files/uploads/fur7284XcgdcV -``` - -**Response** - -```json -[ - { - “submission_id” : “ad6834ffec”, - “code” : 200, - “message” : “Success” - }, - - { - “submission_id” : “3684dafecb”, - “code” : 200, - “message” : “Success” - }, - - { - “submission_id” : “7ffcdea458”, - “code” : 1500 - “message” : “Package live in store” - } -] -``` - -* The API returns a batch response for each item, which includes a `code` and `message`. -* A 200 OK HTTP response code indicates a successful upload. -* Any non-200 HTTP response code indicates an error. -* If no packages are associated with a file, the API returns an empty list and the file is removed.