Re: Content of URL picked by Intent

On Wed, Oct 3, 2012 at 2:58 PM, ⅔ Steve McKay <smckay@google.com> wrote:

> > type "x" when they mean "x;single=true"
>
> This is the case I'm focused on. I suspect we'll see many more Web Intents
> clients being written that Web Intents services. And I suspect we'll see
> the singular case as being the norm.
>
>    - share a URL
>    - pick an image for my profile
>    - bookmark this page
>    - save this text
>    - edit this image
>    - subscribe to this RSS feed
>
> It feels a bit like the tail wagging the dog to normalize around plural
> values.
>
> Why doom legions of developers to a "Whaat the...!?" moment with
> "image/png;single=true" (and the associated junk of having to dress up
> single payload values in an array), when the natural form ("image/png") is,
> well, so perfectly natural?
>
>

The point isn't that you have to specify single=true with a single value.
The issue is one of supporting multiple values or not. It's totally legal
to send a single value through "image/*".

The reason to use an array is for type consistency, so that consuming
single and multiple types don't require different code paths. We expect
supporting multiple values to be the norm, so that's the reason for making
it the default.



> Steve McKay | Engineering |  smckay@google.com | 310-359-8331
>
>
>
>
> On Tue, Oct 2, 2012 at 4:43 PM, Greg Billock <gbillock@google.com> wrote:
>
>> The expectation is the services will support multiple values, even if
>> passing single values is the norm. The choice of which to make the default
>> is partially motivated by the desire to have that be true.
>>
>> The other factor is that the harm to be prevented is a client saying
>> something like "save these 10 files" and the service saving the first one
>> and returning Success. If a service supports multiple values, then it will
>> handle single values without error. If it will handle single values,
>> however, then passing multiple values may result in error. So the parameter
>> that needs to be explicit is a service handling a single value.
>>
>> This puts the main burden on service provider authors, who need to do the
>> right thing to support both variants if they can. It is MIME-pure in that
>> it uses the same data type for the same type/subtype, with the parameter
>> just specifying an encoding detail. There's still an error-proneness for
>> clients saying type "x" when they mean "x;single=true", but that's a more
>> acceptable failure mode than the reverse -- a user can learn that
>> limitation and work around it.
>>
>>
>
>
>
>>
>> On Tue, Oct 2, 2012 at 2:44 PM, ⅔ Steve McKay <smckay@google.com> wrote:
>>
>>> I'm curious about the rationale for denoting "single" as the exceptional
>>> case, rather than multiple? In my admittedly idle speculation, single seems
>>> to be the norm, so why force people to call it out? Also, you and I had
>>> discussed (in person) the use of MIME-type parameters as a means of
>>> declaring the "multiple" nature. When did "multiple" get flipped to
>>> "single" and what's the rationale?
>>>
>>>  Steve McKay | Engineering |  smckay@google.com | 310-359-8331
>>>
>>>
>>>
>>>
>>> On Wed, Sep 26, 2012 at 10:44 AM, Greg Billock <gbillock@google.com>wrote:
>>>
>>>> I was just talking to Alex at the virtual water cooler, and here's a
>>>> proposal I think solves the issues we are wrestling with in an elegant
>>>> way.
>>>>
>>>> 1. All interchange through MIME type specifiers is done with array
>>>> types. That is, if I say "image/png" I will pass [ { ... }, { ... } ].
>>>> Formally, that's sequence<MimeTypeIntentData>. This goes for wildcards
>>>> as well, so "image/*" or "video/*".
>>>>
>>>> 2. We introduce a MIME type parameter indicating that the array will
>>>> contain a single value. So if a service will only produce a single
>>>> value, it can say "image/*;single=true". This explicitly marks a
>>>> client or service as only handling a single value. The harm to be
>>>> avoided is the mismatch of a service or client that will only handle a
>>>> single value, and the other party producing multiple values, which are
>>>> then ignored. For example, a "save" intent service which only saves
>>>> the first value, and then returns SUCCESS, would be very unexpected to
>>>> the client which sent it eight things to save and received that
>>>> SUCCESS response.
>>>>
>>>> This approach achieves the following goals:
>>>>
>>>> a. Keeps the types consistent across all uses -- that makes it easy to
>>>> explain and learn.
>>>> b. Puts the burden of annotation on the service, not the client. If
>>>> the client sends "image/*" with one value, then obviously a service
>>>> that accepts multiple values can handle that. If a client does a
>>>> "pick":"image/*" and the service returns multiple values, the client
>>>> may only use the first one, but that is out of the control of the
>>>> service. The user can learn the capability of the tool and accomodate
>>>> that.
>>>> c. Respect the MIME type semantics. The single=true parameter
>>>> qualifies the type for the service for no surprises, but does not
>>>> change the interchange format (an array).
>>>>
>>>> The only worry I have remaining is that for single values, developers
>>>> may be tempted to use direct object indexing. But I think maintaining
>>>> type consistency is really important, and there are plenty of other
>>>> platform APIs that use a similar convention, so I think this is a
>>>> soluble problem.
>>>>
>>>> Please speak up if there are any objections to this -- I'm planning on
>>>> modifying the web intents wiki document to reflect this [1], but if
>>>> the TF desires, we can draw up a more formal document about this.
>>>>
>>>> [1] http://www.w3.org/wiki/WebIntents/MIME_Types
>>>>
>>>>
>>>> On Tue, Sep 25, 2012 at 9:30 AM, Alex Russell <slightlyoff@google.com>
>>>> wrote:
>>>> > Sorry for the slow response here. Inline:
>>>> >
>>>> >
>>>> > On Thu, Sep 20, 2012 at 7:34 PM, Brett van Zuiden <
>>>> brettcvz@filepicker.io>
>>>> > wrote:
>>>> >>
>>>> >> Hi there - I'm typically just an observer here, but felt like this
>>>> was an
>>>> >> area where we can share a lot of what we have learned.
>>>> >>
>>>> >> I'm one of the founders of Filepicker.io, and our first product has
>>>> strong
>>>> >> parallels to web intents. We've had thousands of developers use our
>>>> product
>>>> >> over the last handful of months, so have some real-life experience in
>>>> >> interacting with developers around the api.
>>>> >>
>>>> >> Our initial approach was to treat multiple as a flag to the getFile
>>>> call
>>>> >> (our equivalent of the "pick" intent). If multiple wasn't set, we
>>>> would
>>>> >> return the url and data as an object, if it was we would return an
>>>> array.
>>>> >> I'm convinced this is the wrong way to do multiple, and that the
>>>> right way
>>>> >> is to have an explicit pickMultiple call.
>>>> >>
>>>> >> Rationale:
>>>> >> * a {"multiple": true} flag has poor discoverability. I'm fairly
>>>> happy
>>>> >> with our documentation, but we still get on average one question a
>>>> week from
>>>> >> people asking if they can/how to select multiple files
>>>> >
>>>> >
>>>> > Agreed.
>>>> >
>>>> >>
>>>> >> * The use cases for selecting multiple files are fairly distinct from
>>>> >> those asking for single files. We initially thought the flag would
>>>> help
>>>> >> people switch between the two - in practice, this rarely happens.
>>>> >> * We've found that the user interface for selecting multiple files
>>>> should
>>>> >> be reasonably distinct from selecting a single file. For instance,
>>>> the
>>>> >> presence of a "shelf" where selected files are queued before being
>>>> submitted
>>>> >> * Making single-file pick an array creates a significant boiler-plate
>>>> >> issue where every implementation needs the same blob of code. It
>>>> also raises
>>>> >> questions about edge cases: what happens if the user closes without
>>>> >> selecting any file? Can an empty array ever be returned for a
>>>> single-file
>>>> >> pick? Will the length of the array always be identically 1?
>>>> >
>>>> >
>>>> > I'm sympathetic to this, but the "boilerplate" is also what makes you
>>>> > automatically able to handle a SEND_MULTIPLE style of intent. The
>>>> default,
>>>> > correct way to write a receiver in this world is also the way to
>>>> implement
>>>> > both single and multiple item receipt. It's surely less overhead than
>>>> > writing the same thing in the SEND_MULTIPLE version and then having a
>>>> > single-item handler as well, isn't it?
>>>> >
>>>> >>
>>>> >> Happy to provide more insights into what we've learned from our
>>>> customers.
>>>> >> We've recently spec'd out the next version of our API and so have
>>>> aggregated
>>>> >> quite a bit of experience into that document.
>>>> >>
>>>> >> - Brett van Zuiden
>>>> >> Founder | Filepicker.io
>>>> >>
>>>> >>
>>>> >> On Thu, Sep 20, 2012 at 1:56 PM, Greg Billock <gbillock@google.com>
>>>> wrote:
>>>> >>>
>>>> >>> On Thu, Sep 20, 2012 at 10:43 AM, Tobie Langel <tobie@fb..com>
>>>> wrote:
>>>> >>> > On 9/20/12 7:27 PM, "Greg Billock" <gbillock@google.com> wrote:
>>>> >>> >
>>>> >>> >>The discomfort I'm estimating as the most acute
>>>> >>> >>is client developers wanting to get started. I'd like them to
>>>> have as
>>>> >>> >>few problems as possible using the API, and so I'd like to make
>>>> their
>>>> >>> >>path as clear as possible.
>>>> >>> >
>>>> >>> > That's actually easily mitigated by providing example code
>>>> developers
>>>> >>> > can
>>>> >>> > copy. It also an issue during a relatively short period of time
>>>> and is
>>>> >>> > relevant to that particular API only. It's also very possible
>>>> that the
>>>> >>> > developers will be familiar with the pattern having seen it
>>>> elsewhere.
>>>> >>> >
>>>> >>> > However, inconsistencies in the platform hurt the productivity of
>>>> >>> > beginner, intermediate and seasoned developers alike. Not only
>>>> does it
>>>> >>> > hurt developers when they are using that particular API, but it
>>>> also
>>>> >>> > hurts
>>>> >>> > them **every time they will use any other API where consistency
>>>> with
>>>> >>> > that
>>>> >>> > particular API would have been expected.** In other words, coming
>>>> up a
>>>> >>> > custom solution here diminishes the quality of the platform as a
>>>> >>> > whole..
>>>> >>>
>>>> >>> I completely agree, and that's a major source of discomfort I'd
>>>> dearly
>>>> >>> like to avoid. :-) If we can document around early pitfalls and give
>>>> >>> developers touching a lot of the platform a consistent experience,
>>>> >>> that's definitely where the balance of intuition ends up lying. I
>>>> >>> definitely think using arrays for multiple MIME values is the way to
>>>> >>> go, and accords well with the rest of the platform. The question is
>>>> >>> how to best indicate that. Always using them is a good approach that
>>>> >>> will work fine.
>>>> >>>
>>>> >>
>>>> >
>>>>
>>>>
>>>
>>
>