Re: Content of URL picked by Intent

LGTM.

--tobie

On 9/26/12 7:55 PM, "Alex Russell" <slightlyoff@google.com> wrote:

>+1!
>On Sep 26, 2012 6:44 PM, "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.
>>>>
>>>
>>
>
>
>

Received on Wednesday, 26 September 2012 17:59:14 UTC