Replies: 3 comments 19 replies
-
|
More detailed notes and examples for review. Media Upload using Pre-signed URLsThis is a proposed solution to media upload. Data RepresentationData StructureThese are the required fields to represent the upload process for media <EntityType Name="Media">
<Property Name="PresignedUrl" Type="Edm.String" />
<Property Name="PresignedUrlExpiry" Type="Edm.DateTimeOffset" />
<Property Name="MediaStatus" Type="Edm.String" />
<Property Name="MediaStatusDescription" Type="Edm.String" />
</EntityType>Status of the MediaThe status of the media will be tracked on the
Some examples of
Media Upload Process - Happy PathThe creation of the media resource will be done using as a standard Odate Update Process. (Defined in RCP-10). The post should included all known metadata about the media with the exception of only the media byte stream. If the media is a reference to external URL reference, the server should ingest the Create Media ResourceCreate the initial media record using the Data standard. This could be an expanded record on another resource a secondary approach but the example will be with REQUEST POST https://api.my-webapi.io/Media
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representation{
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
}RESPONSE HTTP/2 201 Created
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Incomplete",
"MediaStatusDescription": "Awaiting Byte Stream",
"PresignedUrl": "https://storage.my-webapi.io/media/12345.jpg?authentication_token=my-one-time-use-auth-token-12345-zyxwut",
"PresignedUrlExpiry": "2023-08-01T13:00:00+00:00",
}The return from the POST will return a pre-signed URL with an validity window for that URL. Upload the Media byte arrayThie bytestrem upload will be a simple HTTP POST transaction to the provided to the endpoint with no other required data. No external fields, headers or payloads are required to post the media stream. All requirements for the POST must be part of the REQUEST RESPONSE Media post processingThe original media record will transition to If any processing fails, the media record will be have a status of Rules can be written against the Successful Media UploadThe media record can up queries to confirm the media has successfully been processed. REQUEST POST https://api.my-webapi.io/Media('12345')
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representationRESPONSE HTTP/2 200
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Complete",
"MediaStatusDescription": "Processing Complete",
"PresignedUrl": null,
"PresignedUrlExpiry": null,
}Media Upload Process error statesThese are the cases where the media record will not reach the Media Record created but no byte stream providedThis will leave the media record in a REQUEST POST https://api.my-webapi.io/Media('12345')
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representationRESPONSE HTTP/2 200
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Incomplete",
"MediaStatusDescription": "Awaiting Byte Stream",
"PresignedUrl": "https://storage.my-webapi.io/media/12345.jpg?authentication_token=my-one-time-use-auth-token-12345-zyxwut",
"PresignedUrlExpiry": "2023-08-01T13:00:00+00:00",
}PresignedUrl ExpiresIf a Refreshed CaseREQUEST POST https://api.my-webapi.io/Media('12345')
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representationRESPONSE HTTP/2 200
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Incomplete",
"MediaStatusDescription": "Awaiting Byte Stream",
"PresignedUrl": "https://storage.my-webapi.io/media/12345.jpg?authentication_token=my-one-time-use-auth-token-12345-abcdefg",
"PresignedUrlExpiry": "2023-09-01T14:00:00+00:00",
}Rejected CaseREQUEST POST https://api.my-webapi.io/Media('12345')
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representationRESPONSE HTTP/2 200
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Rejected",
"MediaStatusDescription": "Media record has timed out",
"PresignedUrl": null,
"PresignedUrlExpiry": null,
}Media uploaded but byte stream rejectedIf the media is rejected, the vendor can eithe allow for the record update by providing the Resubmit CaseREQUEST POST https://api.my-webapi.io/Media('12345')
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representationRESPONSE HTTP/2 200
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Rejected",
"MediaStatusDescription": "Byte stream is not of type image/jpeg",
"PresignedUrl": "https://storage.my-webapi.io/media/12345-attempt2.jpg?authentication_token=my-one-time-use-auth-token-12345-abcdefg",
"PresignedUrlExpiry": "2023-09-01T14:00:00+00:00",
}Write-Once CaseREQUEST POST https://api.my-webapi.io/Media('12345')
OData-Version: 4.01
Content-Type: application/json
Accept: application/json
Prefer: return=representationRESPONSE HTTP/2 200
OData-Version: 4.01
EntityId: "12345"
Location: https://api.my-webapi.io/Media('12345')
Content-Length: 200
Content-Type: application/json
Preference-Applied: return=representation{
"@OData.context":"https://api.my-webapi.io/$metadata#Media/$entity",
"@OData.id":"https://api.my-webapi.io/Media('12345')",
"@OData.editLink":"https://api.webapi.io/Media('12345')",
"@OData.etag": "W/\"aBcDeFgHiJkLmNoPqRsTuVwXyz\"",
"MediaObjectID": "12345",
"Caption": "Ipsum Lorum",
"Order": 1,
"ImageType": "image/jpeg",
"MediaStatus": "Rejected",
"MediaStatusDescription": "Byte stream is not of type image/jpeg",
"PresignedUrl": null,
"PresignedUrlExpiry": null,
} |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for putting this together. I think we should talk about some of this a bit. |
Beta Was this translation helpful? Give feedback.
-
|
Completely agree we should discuss this now in the discussion/proposal stage now. I did not like the two approaches either. I would prefer for it to be uniform. If in the case where the PresignedURL is a collection size of one, it behaves in a simple HTTP POST model, then I like this approach. This way those implementations that only want to support simple HTTP POST would only ever return an array of one and those that want to support multi-part can implement as they feel the need. The implementations can also make the decision on which way to go based on the proposed byte length of the media byte stream. This approach would however require the use of separate HTTP POSTs for each part (no multi-part MIME) as the differences communicated in the PresignedURLs between parts (partnumber for example) would be encoded in the The simple HTTP POST allows implementers to avoid an extra layer of infrastructure to meet the WebApi spec. The additional complexity and cost of supporting multi-part comes from the fact that a multi-part upload solution requires a custom code, maintenance/admin/upkeep and the compute to process the records through it and push them to media storage. The original simple HTTP Post approach is the lowest common denominator that could be found between the various object storage solutions (Ceph, S3, Azure Blob, etc.). The single pre-signed HTTP POST approach can be implemented out-of-the-box directly to the object storage without involving a layer of compute to provide chunking functionality. There is no common multi-part upload across object storage vendors (yet). Media is a high volume resource so small changes in compute demand can have large costs. Even if its tenths of a penny per media byte stream, some implementers have millions or tens of millions of new media every month. The costs add up. |
Beta Was this translation helpful? Give feedback.
-
That's the goal in what I'm suggesting: to have separate HTTP posts for each part. Multipart posts and boundaries make things more complicated than a simple post, so the idea is to try and take a similar approach for each part. In terms of things being "transactional," they still would be in the sense that the media record would be marked as "ready" only after each part was uploaded and their checksum passed. It's just that the transaction boundary extends past one HTTP request. Personally, I don't see a problem with that since we have a way to address it. The transaction boundary for things like listings already spans more than one request if you're not posting the entire thing and all its information in one request anyway. Regarding knowing the state of the update, on the client side they know if each part completes or not with HTTP status codes, so it's easy for them to know to retry, if needed. And on the server side, they'd know internally which parts have been completed or not and the MediaStatus field could reflect that. If they have stray parts sitting around after the lifetime of the URL, remove them. If providers don't support parts, for some reason, then if someone tried to request a pre-signed URL for media that was too large for them to accept in one POST, they could just fail, hopefully with a meaningful error message. Otherwise give a single URL back in the response. If they later decide to add this functionality, the interface doesn't need to change and doesn't require multiple interfaces to perform the same task. The simplicity of one image per post is nice, but I think it's too limiting. If people want to post high quality photos, videos, floor plans, or any other media that may come along in the future, the standards shouldn't limit them to the internal requirements of whatever cloud provider their vendors chose. As a side note, I'm not suggesting the differentiating factor with parts are the URLs themselves, since you mentioned it. That was just an example. They could be the same URL with parameters. That would be up to the vendor to decide. I think it also makes sense that the more complex case should reuse elements of the simple case so that the interface is consistent and data models aren't totally different in both cases. Makes things more complicated. |
Beta Was this translation helpful? Give feedback.
-
|
We are on the same page. multi-part MIME has no value to be supported.
If there is any reason for a client to retransmit a part that received a previous successful response we could have problems with the server automatically changing media state to upload-complete once all parts have been used once. We have an implicit complete vs explicit complete transition. How long should the server wait for for any pending updates before transitioning to complete? Not being able to force media to a upload-complete state quickly will block making the listing active as many systems have rules "at least one validated photo must be on the listing before property state can be active". Conversely systems also have WORM policies on media, once a media record is upload-complete, it cannot be touched again. I would like there to be a timeout for this when implicit but have an explicit way for the client to push it so their changes can get to market faster.
This would be the standard HTTP 413 - Entity too large that some vendors already use to communicate their max image sizes with RETS today.
We are talking about supported single post sizes today of 2 or 5 GB range on the major vendors (see links in previous post) so the limitation will like be the implementers arbitrary size enforcement rather than storage vendor enforced. This would meet the 99% case but having support available for multi-part upload is good.
I only inferred it because I did not want to change your example and it was a good place to put it. While it might be part 4 for a given media record, the implementation specific identifier could easily be some other key -- UUID. other global sequence, etc. To avoid getting into implementation specific details, we should extend the self contained nature of the of the pre-signed URLs that we expressed originally. The pre-signed URL must contain all information to authenticate and identify the byte stream object (including part information) that will be posted. To summarize a example workflow:
|
Beta Was this translation helpful? Give feedback.
-
|
I think one way to address the transaction is to ask the client to post an upload complete? Also, we might want the client to provide a checksum on each part in addition to the total? For the pre-signed URLs returned, they should be opaque to the client? They should just post each part as returned in the URLs? |
Beta Was this translation helpful? Give feedback.
-
|
For the upload complete, reusing the For Checksums, I would suggest that we add it as an optional header like The clients should use the URLs as-is for each part they are going to post. There should be no transformation logic applied to them. The implementations should supply clean endpoint URLs that will accept the HTTP POST of that segment of the byte stream. |
Beta Was this translation helpful? Give feedback.
-
|
This discussion should be closed and the discussion should move to #116 which is the new OData version of the proposal. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Step 1
Post data to Media resource with all the metadata available for the image prior to uploading the base64 encoded image data.
Note: In this step there are two cases ... either the record that the Media is attached to is included in the initial creation of the Media metadata (ResourceName, ResourceRecordKey), or it isn't. If not, then that information needs to be provided at some point (after step 2).
Step 2
Once the Media record has been created, the client can upload the binary image data by obtaining the pre-signed URL attached to the Media item that was created. The pre-signed URLs will be generated as a result of step (1), and will have an expiration timestamp associated with them.
Media Statuses
We also need to define statuses in the Media Resource to reflect the various stages of processing.
If the record has been rejected for some reason, either processing failed or there was a compliance issue (for example), there will also be a StatusDescription to let clients know what failed.
Beta Was this translation helpful? Give feedback.
All reactions