Re: Content of URL picked by Intent

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