Uploading Media

[clbaxter]

WebAPI ODATA Edit/Insert
Opening a discussion on ODATA usage in uploading media to a system.

ODATA as a framework for transfer of information is not well geared IMO for file transfers but does have some definition as to 2 main approaches to tackle the issue.

1. Media Stream of a Media Entity
   vs
2. inlining stream properties as base64url-encoded values

There are different benefits and detractors on both sides of those options but with ease of use for the end user I believe the second approach is far more usable.
The second approach simply expects the file data to be converted to a Base64 data stream in the body of the request.
This approach does not require the sender to have a reachable URL to be called back to, for the receiving server to fetch the stream of data from, it is already included in the request body.

[codygustafson]

Could we gather a description of how these 2 options function? At face value, I think I would prefer option 1. A bit harder for servers and clients to implement but allows for a much more stable healthier OData servers overall. I do think the size of a request if clients are inserting a listing with all its media should be a serious consideration when considering which of these options to use. I have no desire to proxy base64 encoded photos through our API application. I would much rather give clients a URL to upload to.

[darnjo]

On the OData side, there's more information here:

• Requesting Media Entities
• Streams and $expand
• Creating related media entities
• Updating Media

There are also specific sections in the OData spec regarding Managing Media Entities as well as Stream Properties.

More information on the OData Media Type beyond the protocol.

[codygustafson]

I have seen that content. I still find it difficult to digest as written. Given this documentation, I am not confident I could implement something that would align with other OData servers implementing something at the same time. Maybe this is a scenario a proof of concept or example would be nice.

[darnjo]

I find the documentation a bit unclear as well. It would be good to try and find some working examples in order to provide guidance on the standard.

[clbaxter]

After further review there are more hindrances with embedding media directly in a post. Largely identified by servers having file transfers limited to fixed sizes in direct requests that would make embedding files often limited to "only one file" at a time. This is especially the case where a single photo can be over 20 Megabytes these days, and is only getting larger in the future.
There is a bonus with embedding from the user perspective (in the imagined use..) of an agent uploading a single image directly from a cell phone. Opening easier access to App development and use without an intermedia server.

More often it would be expected that media uploads would come from a server request b2b operation.

Upload requests (POST, PATCH) would be better served by providing media URL's leaving it to the receiving server to fetch/stream said resources appropriately. This looks far more likely to be the bulk use case.

[darnjo]

Makes sense.

In most cases, providing a URL for a streaming media update would likely be preferable. Especially when there are many images to upload.

That said, what about a user trying to upload photos from a mobile app directly to the Web API? Is it reasonable to assume that they'd upload the media to an intermediate location and then stream that to the Media resource from a URL?

[clbaxter]

"this" is the only case that I see arising as likely a common desired case. The ease in developing as app that does NOT need a dedicated server to run while supporting the option to directly upload a resource at a time look very desirable. I think moving towards to future this approach would be wanted, primarily for an agent to add a single photo on the fly directly from any internet connected device.
In contrast though, It is not a current case, and the majority of early WebAPI ODATA Add Edit use will likely remain server based bulk update actions. With this, streaming from given URL's will have to be supported regardless.
Yes, any app developer can also just support media upload via a public hosted URL with a server, but ease of use and access is part of what moving to ODATA structure is here for in the industry as well.

[codygustafson]

One thing I stated in the developer conference as my preference was a pre-signed URL that we can POST to, similar to AWS services. An issue that was brought up during the call was the need to support draft listings if we take that on. An alternative to Draft listings is draft media. If we allow media to be inserted prior to creating the listing, I believe that takes care of that problem.

[clbaxter]

Proposing settling on 'Media Upload' via 2 supported methods. (One, must be available, both would be nice )

1. Embedded file bytes (base64 encoded) as 'single file'
2. Request contains source URL('s) for the target server to pull files from.

In form '2' where upload requester provides a "StatusCallbackURL" after the operation completes (success/fail/partial success) the entity references can be returned (Standard ODATA success operation) Or (ODATA fail message)

[[ Embedded ]]

POST request with minimum parameters

body
{
"MediaType": "PDF",
"OriginalFilename":"MyLisitingDoc.png",
"data":"kj3b45kh3r9yd0cus09dvu94jb&^76dVbussdm]][]{oS8wsejdbkv....."
}

POST request with optional parameters

body
{
"MediaType": "PDF",
"OriginalFilename":"MyLisitingDoc.png",
"data":"kj3b45kh3r9yd0cus09dvu94jb&^76dVbussdm]][]{oS8wsejdbkv....."
"order": 2,
"description" : "this is a test doc as a pdf file",
"short description" : "test pdf doc"
}

[[ source URL('s) ]]

POST request with minimum parameters

body
{
"ResourceRecordKeyNumeric": 12216,
"TableID": 9,
"media":[
{
"MediaType": "photo",
"OriginalFilename": "image1.png",
"MediaPath":"http://myco.media.com/12216/image1.png"
},
{
"MediaType": "photo",
"OriginalFilename": "image2.png",
"MediaPath":"http://myco.media.com/12216/image2.png"
}
]
}

POST request with optional parameters

body
{
"ResourceRecordKeyNumeric": 12216,
"TableID": 9,
"StatusCallbackURL": "http://myco.media.com/uploadstatus/12216"
"media":[
{
"MediaType": "photo",
"OriginalFilename": "image1.png",
"MediaPath":"http://myco.media.com/12216/image1.png",
"LongDescription":"first Image",
"order":1
},
{
"MediaType": "photo",
"OriginalFilename": "image2.png",
"MediaPath":"http://myco.media.com/12216/image2.png",
"LongDescription":"seconds Image",
"order":2
}
]
}

[gr33neggs]

For .NET OData out of the box information I did find some leads:

This adding stream support in the first place for v4
OData/WebApi#328

The above appears to be included in this from 2021
OData/WebApi#2401

This was a v3 example from someone who spoke with the OData Web API team and created a custom solution example:
https://learn.microsoft.com/en-us/archive/blogs/mrtechnocal/media-resource-support-for-odata-in-web-api

OData's vagueness for media update seems to lead to lots of interpretations and custom implementations.

[darnjo]

More research needs to be done as to how OData handles Add/Edit with Media and Streams. Also, is the way OData handles this what we want or are there other ways to address it?

[paulhethmon]

One thought on the client providing a URL to the server to then pull the image is that security policies prevent a lot of servers from making any outbound connections, much less to essentially random URLs.

[darnjo]

See #88 for a new version of the proposal.

[grispin]

Just added examples proposal from the Developer Summit to the Issue #88 ticket

[grispin]

That proposal has be superceded by #116 now

[clbaxter]

Notes on Base64 encoded single file upload processes Post Testing.
Base64 encoding of jpg files increases the file size by ~30%
It looks to be fairly common that servers Block requests when body size is greater than 10MB. This leaves < ~8MB media uploads in the clear for the most part in single embeded upload requests with this method.

[grispin]

@clbaxter At the RESO developer summit we had a long discussion about media and the current proposal is a pre-signed URL approach (see Issue #88 for proposal review). The proposal avoids Base64 entirely as it's wasted bandwidth and processing and has the media byte stream sent raw to the pre-signed URL endpoint .

This solution has a number of desirable:

• The client implementation is very simple. (Basic HTTP Post, no extra encoding, authentication, etc.)
  • Separate posts for each media record. (Simple response parsing, HTTP based horizontal scaling)
• Server side is flexible for implementation.
  • the byte stream does not have to be proxied through the oData endpoint to get the internal
  • Different Signed URL Endpoints can be given for different types of media mime types. (PDFs, TIFF, AVI, JPEG, WEBP, etc.)
  • Photo streams can go directly in to the media processing pipeline (almost all vendors do scaling, watermarking, content ID, etc.)
• Async state of media can be respresented on the meta for the media resource
• Off-the-shelf solutions can be used for object storage (Azure Blob, AWS S3, etc. without a byte stream proxy)

The native Odata byte stream interfaces are designed with attachment to the Odata resource in mind. The RESO use-cases fall outside of the typical workflow as the POSTed byte stream is not a simple attachment.
It is typically manipulated by the vendor (watermarked, scaled, content audited, CDN publish, etc.) before the media is distributed through via the MediaURL field, not the Odata byte stream download methods.

Base64 type solutions add significant overhead when you start to consider larger media like panoramic photos, hi-res videos, virtual tours, multiple page scanned PDF documents, etc. We have seen what this does with RETS (GetObject/PostObject) and it's use of multi-part MIME. We should try to avoid these style approaches where possible.

Odata MediaLink was considered and could be used like a pre-signed URL but MediaLink becomes a required field on the resource for the records entire life. Many vendors have a Write-Once behaviour for the media byte stream due to the async actions that happen after the POST completes (watermarks, image scaling, content ID, CDN publishing, etc.). The availability of the byte stream endpoint in the current Media state can be represented by visibility of data in the PreSignedUrl* fields, this cannot be done with MediaLink which requires more knowledge by the client or the client and getting a 4xx HTTP error code at the MediaLink endpoint.

[grispin]

That proposal have been superceeded by #116 now.