From ed25c7c977a0ea14b8e288cd6b23233fd254955a Mon Sep 17 00:00:00 2001 From: Dewi Morgan Date: Thu, 31 Oct 2019 12:00:08 -0500 Subject: [PATCH 1/2] Update files.md --- marketplace/eqp/v1/files.md | 152 ++++++++++++++++-------------------- 1 file changed, 66 insertions(+), 86 deletions(-) diff --git a/marketplace/eqp/v1/files.md b/marketplace/eqp/v1/files.md index d6ecf6f147b..edb3660e437 100644 --- a/marketplace/eqp/v1/files.md +++ b/marketplace/eqp/v1/files.md @@ -11,11 +11,14 @@ Use `files` resources to manage all code artifacts and assets associated with an * 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). +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 +27,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 +37,20 @@ 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.| +{:.style="table-layout: auto;"} + +Sorting and filtering parameters are not currently 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 +64,62 @@ 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.| +|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.| {:.style="table-layout: auto;"} +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. +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 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 +133,23 @@ 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.| +{:.style="table-layout: auto;"} **Request** +If the request body given above was saved into a temporary file at `/tmp/files-payload`, +you could use it in your POST request to upload the files: + ```bash curl -X POST \ -H 'Authorization: Bearer baGXoStRuR9VCDFQGZNzgNqbqu5WUwlr.cAxZJ9m22Le7' \ @@ -130,34 +160,36 @@ curl -X POST \ **Response** +The above request could give 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" } ] ``` @@ -176,55 +208,3 @@ Each record in the list has the following fields: {:.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. From 6567a828f723f59f54cd46e0f167dd53c294d639 Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Thu, 31 Oct 2019 14:05:18 -0500 Subject: [PATCH 2/2] Grammar and formatting --- marketplace/eqp/v1/files.md | 38 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 22 deletions(-) diff --git a/marketplace/eqp/v1/files.md b/marketplace/eqp/v1/files.md index edb3660e437..827e04a30e6 100644 --- a/marketplace/eqp/v1/files.md +++ b/marketplace/eqp/v1/files.md @@ -5,14 +5,13 @@ 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). +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. @@ -44,12 +43,11 @@ GET /rest/v1/files/uploads/:file_upload_id |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.| -{:.style="table-layout: auto;"} -Sorting and filtering parameters are not currently available for this endpoint. +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. +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** @@ -88,15 +86,13 @@ Response field details: |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.| -{:.style="table-layout: auto;"} 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 could otherwise 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 @@ -133,9 +129,9 @@ Content-Type: application/pdf ------------287032381131322-- ``` -* 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: +- 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: |Element|Type|Description| |-----|--------|-----------| @@ -143,12 +139,11 @@ Content-Type: application/pdf |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.| -{:.style="table-layout: auto;"} **Request** If the request body given above was saved into a temporary file at `/tmp/files-payload`, -you could use it in your POST request to upload the files: +you may use it in your POST request to upload the files: ```bash curl -X POST \ @@ -160,7 +155,7 @@ curl -X POST \ **Response** -The above request could give output similar to: +The above request gives an output similar to: ```json [ @@ -205,6 +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.