PB-615: Spec multipart upload process #425
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,6 +30,7 @@ tags: | |
|
|
||
| | Media Type | Description | File Extension(s) | | ||
| | ---------- | ----------- | ----------------- | | ||
| | application/vnd.apache.parquet | Apache Parquet column-oriented data file format | .parquet | | ||
| | application/x.ascii-grid+zip | Zipped ESRI ASCII raster format (.asc) | .zip | | ||
| | application/x.ascii-xyz+zip | Zipped XYZ (.xyz) | .zip | | ||
| | application/x.e00+zip | Zipped e00 | .zip | | ||
|
|
@@ -60,6 +61,8 @@ tags: | |
| | application/x.geojson+zip | Zipped GeoJSON | .zip | | ||
| | application/x.interlis; version=2.3 | Interlis 2 | .xtf, .xml | | ||
| | application/x.interlis+zip; version=2.3 | Zipped XTF (2.3) | .zip | | ||
| | application/x.interlis; version=2.4 | Interlis 2 | .xtf | .xml | | ||
| | application/x.interlis+zip; version=2.4 | Zipped XTF (2.4) | .zip | | ||
| | application/x.interlis; version=1 | Interlis 1 | .itf | | ||
| | application/x.interlis+zip; version=1 | Zipped ITF | .zip | | ||
| | image/tiff; application=geotiff; profile=cloud-optimized | Cloud Optimized GeoTIFF (COG) | .tiff, .tif |` | ||
|
|
@@ -92,6 +95,34 @@ tags: | |
| - <span style="color:red">*Files bigger than 10 MB should use compression, | ||
| see [Compression](#section/Compression)*</span> | ||
|
|
||
| ## Steps to upload Assets | ||
|
|
||
| To upload an assets file there are generally three steps involved: | ||
|
|
||
| <ol> | ||
| <li>Create new upload process</li> | ||
| <li>Upload parts/files</li> | ||
| <li>Complete upload process</li> | ||
| </ol> | ||
|
|
||
| Any file that is larger than 5 GB must be split into multiple parts. A file part must be at | ||
| least 5 MB except for the last one and at most 5 GB, otherwise the complete operation will fail. | ||
| If the file is less that 5 GB, you will only upload a single part, but must still start and complete the process as with multiple parts. | ||
|
|
||
| (1) Use the [create new upload](#tag/Asset-Upload-Management/operation/createAssetUpload) request to start a new upload. | ||
| It will return a list of urls. | ||
|
|
||
| (2) Use the urls to [upload asset file part](#tag/Asset-Upload-Management/operation/uploadAssetFilePart). Do this for each file part. | ||
|
|
||
| (3) Once all parts have been uploaded, execute the [complete the upload](#tag/Asset-Upload-Management/operation/completeMultipartUpload) request. | ||
| The new asset file be available to users after you have successfully completed the upload. | ||
|
|
||
| If any errors happen during the upload process, you can [abort the upload](#tag/Asset-Upload-Management/operation/abortMultipartUpload) | ||
| and restart the process. | ||
|
|
||
| There can only be 1 upload in progress per asset. If you wish to start a new upload you must first abort any existing upload that is in progress. | ||
|
There was a problem hiding this comment. I think this is a bit unclear. From my understanding it's OK to upload multiple parts concurrently but you cannot "overwrite" (start a new upload of) an asset for which upload has not completed (or been aborted). There was a problem hiding this comment. Maybe a link to this doc might be useful somewhere here: https://github.com/geoadmin/service-stac/blob/develop/doc/stac-upload-error-handling.md There was a problem hiding this comment. Esp. the flow chart could be of interest to some users There was a problem hiding this comment. I wasn't aware of that doc. Maybe it should be pulled into the API doc itself instead of being a separate document? If it needs to remain separate, I strongly support linking to it. There was a problem hiding this comment. Adapted the concurrent upload part sentence. I was also not aware of this document. I added the detailed description of the upload to the spec, as well as the diagram asset to the static files. There was a problem hiding this comment. I suggest replacing the document with a redirect to the API doc that has the content. Less copypasta to maintain. There was a problem hiding this comment. Yes, I removed the existing file as all the content is integrated in the spec. Also moved both diagram files to the static assets. |
||
| Use [list uploads](#tag/Asset-Upload-Management/operation/getAssetUploads) to see if any uploads | ||
| are in progress. | ||
|
|
||
| ## Authentication | ||
|
|
||
|
|
@@ -571,7 +602,9 @@ paths: | |
| $ref: "#/components/responses/ServerError" | ||
| delete: | ||
| summary: Delete an existing feature by Id | ||
| description: | | ||
| Use this method to delete an existing feature/item. The feature can only be deleted if all | ||
| its assets have been deleted first. Also see [Delete an existing asset by id](#tag/Data-Management/operation/deleteAsset). | ||
|
There was a problem hiding this comment. "See also" sounds less weird than "Also see" I think. |
||
| operationId: deleteFeature | ||
| tags: | ||
| - Data Management | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How about "except for the last (or only) one" ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If we want to call it out, I would add a separate sentence instead of parenthesis. "If there is only one part, it can be smaller than 5 MB since it is also the last part."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Following this sentence there is the following sentence:
"If the file is less that 5 GB, you will only upload a single part, but must still start and complete the process as with multiple parts."
Do you think it needs more than this?