Re: Content of URL picked by Intent

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

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