Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Update files.md #5896

Merged
merged 2 commits into from
Oct 31, 2019
Merged

Update files.md #5896

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ed25c7c
Update files.md
dewimagento Oct 31, 2019
6567a82
Grammar and formatting
dobooth Oct 31, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 66 additions & 92 deletions marketplace/eqp/v1/files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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/<hash of mag12345>/pub/1c/ee/<full file_hash>/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

<zip file content here.....>

------------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

<image file content here.....>

------------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

<image file content here.....>
Expand All @@ -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' \
Expand All @@ -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"
}
]
```
Expand All @@ -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.