Comments on the first draft of the OpenFile API Design
Anton Bar
Hi Adam,
I learned the spec and have several comments:
1. OpenFile provider URL
I propose to change "There MUST
be a form on the Client where the User can enter the URL" to "There MUST be a
form on a Client where the User can chose a Service Provider from a predefined
list or enter URL of another Service Provider manually. Client is RECOMMENDED to
allow Users to add, modify, reorder, and delete Service Providers per User's
account".
2. Client
You use the term Client and the closely related
OAuth uses the term Consumer. I prefer Client, but maybe we should play along with them?
2. Service Document
How about using XRDS? (for more info
see Yadis http://yadis.org/wiki/Main_Page and
OAuth Discover http://oauth-specs.googlecode.com/svn/discovery/1.0/drafts/1/spec.html).
3. File Access
You specify how to permit reading/writing
files but leave the following topics unanswered:
- Create / Delete files - I assume Create now is part of Write, but maybe it should be a separated permission.
- Read / Create / Delete directories - Read directory = enumerate files.
- Read all files - It can be useful to allow reading all files from a specified directory (we can use "folder/*" technique as shown in the examples below)
- Write only - I think Write Only ("w") permission can also be useful.
How about defining User's permissions on base of REST path, which can be either file or directory?
For example:
<link allow="r" href="http://api.g.ho.st/rest/users/adam/trips/paris/eiffel.jpg"
/> <!-- permission to read the "eiffel.jpg" file
-->
<link allow="r" href="http://api.g.ho.st/rest/users/adam/public/docs/"
/> <!-- permission to enumerate files from "docs"
folder -->
<link allow="r" href="http://api.g.ho.st/rest/users/adam/public/docs/*"
/> <!-- permission to read files from "docs" folder
-->
<link allow="rw" href="http://api.g.ho.st/rest/users/adam/public/inbox/*"
/> <!-- permission to read and write all files in the
"inbox" folder -->
4. Open / Save As
Dialogs
If the File Access proposal is acceptable, then
maybe we don't have to enforce the Service Providers providing File Open /
SaveAs dialogs in dedicated URLs. Clients will use the File System REST API and
design these dialogs themselves. Hence, the dialogs will have the Client's
specific look-n-feel and will avoid the possible cross-domain scripting
problem.
I have more thoughts, but first lets see if the above makes sense.
What do you think?
Anton Bar
Chief Gheek
G.ho.st... No walls
Skype: antonbar
Office: +972-8-975-55-60 x3201
Fax: +972-8-975-55-70
Mobile: +972-54-620-24-40
______________________________
______
Sent from my free G.ho.st Virtual Computer
Adam Rosien
> 1. OpenFile provider URL
> I propose to change "There MUST be a form on the Client where the User can
> enter the URL" to "There MUST be a form on a Client where the User can chose
> a Service Provider from a predefined list or enter URL of another Service
> Provider manually. Client is RECOMMENDED to allow Users to add, modify,
> reorder, and delete Service Providers per User's account".
I don't think it's a good idea to require a Client to have a
predefined list of providers, but we can certainly recommend it as a
good practice. I think your second idea of allowing Users to link
their SP with their account is a good recommendation and would improve
the user experience.
> 2. Client
> You use the term Client and the closely related OAuth uses the term
> Consumer. I prefer Client, but maybe we should play along with them?
I've never liked the use of Consumer as it confuses me with a user of
software. I prefer Client unless a lot more people find it confusing.
> 2. Service Document
> How about using XRDS? (for more info see Yadis
> http://yadis.org/wiki/Main_Page and OAuth Discover
> http://oauth-specs.googlecode.com/svn/discovery/1.0/drafts/1/spec.html).
Looks like a great idea especially since we require OAuth. I'll look into it.
> 3. File Access
> You specify how to permit reading/writing files but leave the following
> topics unanswered:
> Create / Delete files - I assume Create now is part of Write, but maybe it
> should be a separated permission.
> Read / Create / Delete directories - Read directory = enumerate files.
> Read all files - It can be useful to allow reading all files from a
> specified directory (we can use "folder/*" technique as shown in the
> examples below)
> Write only - I think Write Only ("w") permission can also be useful.
I agree that the "allow" attribute is too limited as is, especially
since it is intended to capture the HTTP methods allowed for the
resource in the href attribute. In fact, I would propose changing the
meaning and syntax of the allow attribute to exactly the same as the
Allow header in HTTP
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.7).
Performing an OPTIONS request on the resource would give the same
response. Thus allow="GET, PUT" for read/write, allow="POST" for
create, etc., in the usual CRUD to HTTP method mapping.
In some ways I'm beginning to think we're making an ACL (access
control list) protocol with specific uses for delegated file
operations.
> How about defining User's permissions on base of REST path, which can be
> either file or directory?
I don't want to define meaning of the Service Provider's URL schema
that says if a URL looks like this, then it's a file, and if it looks
like that, then it's a directory. The content type of the links in
the AFL are a better way to encode this.
> 4. Open / Save As Dialogs
> If the File Access proposal is acceptable, then maybe we don't have to
> enforce the Service Providers providing File Open / SaveAs dialogs in
> dedicated URLs. Clients will use the File System REST API and design these
> dialogs themselves. Hence, the dialogs will have the Client's specific
> look-n-feel and will avoid the possible cross-domain scripting problem.
I think the dedicated Open/SaveAs dialog URLs are required to
implement the major goal of minimizing the Client's access to data in
the Service Provider. I would like to give the User the most control
over their data, which means that the dialogs must be in the SP rather
than the Client.
I certainly think that your idea can work, but in my mind it still
requires an initial authorization via a Open Dialog. For example,
imagine a Client that is a file system browser. Initially the Client
is denied access to a User's data in the SP. The Client requests
access via the Open Dialog, and the User grants the Client full
permissions. The Client is then returned a AFL with a URL that points
to the "top" of the file system--with some content type like HTML or
Atom or the WebDAV properties type--and the Client can then browse the
data on the SP.
You could implement your idea and this example with just OAuth, but
you'd be giving up the explicit control the User gets, which is
important to me.
.. Adam
Anton Bar
> > 1. OpenFile provider URL
> > I propose to change "There MUST be a form on the Client where the User can
> > enter the URL" to "There MUST be a form on a Client where the User can chose
> > a Service Provider from a predefined list or enter URL of another Service
> > Provider manually. Client is RECOMMENDED to allow Users to add, modify,
> > reorder, and delete Service Providers per User's account".
>
> I don't think it's a good idea to require a Client to have a
> predefined list of providers, but we can certainly recommend it as a
> good practice. I think your second idea of allowing Users to link
> their SP with their account is a good recommendation and would improve
> the user experience.
No, I didn't mean to require a predefined list. Please read again, I proposed "MUST... predefined list OR enter URL...", so it actually gives Clients two options and hence more freedom than your proposal.
> > 2. Client
> > You use the term Client and the closely related OAuth uses the term
> > Consumer. I prefer Client, but maybe we should play along with them?
>
> I've never liked the use of Consumer as it confuses me with a user of
> software. I prefer Client unless a lot more people find it confusing.
So do I, maybe we can suggest them using the Client term...
> > 3. File Access
> > You specify how to permit reading/writing files but leave the following
> > topics unanswered:
> > Create / Delete files - I assume Create now is part of Write, but maybe it
> > should be a separated permission.
> > Read / Create / Delete directories - Read directory = enumerate files.
> > Read all files - It can be useful to allow reading all files from a
> > specified directory (we can use "folder/*" technique as shown in the
> > examples below)
> > Write only - I think Write Only ("w") permission can also be useful.
>
> I agree that the "allow" attribute is too limited as is, especially
> since it is intended to capture the HTTP methods allowed for the
> resource in the href attribute. In fact, I would propose changing the
> meaning and syntax of the allow attribute to exactly the same as the
> Allow header in HTTP
> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.7).
> Performing an OPTIONS request on the resource would give the same
> response. Thus allow="GET, PUT" for read/write, allow="POST" for
> create, etc., in the usual CRUD to HTTP method mapping.
Great, I like it!
> In some ways I'm beginning to think we're making an ACL (access
> control list) protocol with specific uses for delegated file
> operations.
>
> > How about defining User's permissions on base of REST path, which can be
> > either file or directory?
>
> I don't want to define meaning of the Service Provider's URL schema
> that says if a URL looks like this, then it's a file, and if it looks
> like that, then it's a directory. The content type of the links in
> the AFL are a better way to encode this.
Agreed, what's important for me is a logical distinction between groups of items (directories) that you can create/delete or enumerate and items (files) that you can create/delete/read/write.
> > 4. Open / Save As Dialogs
> > If the File Access proposal is acceptable, then maybe we don't have to
> > enforce the Service Providers providing File Open / SaveAs dialogs in
> > dedicated URLs. Clients will use the File System REST API and design these
> > dialogs themselves. Hence, the dialogs will have the Client's specific
> > look-n-feel and will avoid the possible cross-domain scripting problem.
>
> I think the dedicated Open/SaveAs dialog URLs are required to
> implement the major goal of minimizing the Client's access to data in
> the Service Provider. I would like to give the User the most control
> over their data, which means that the dialogs must be in the SP rather
> than the Client.
>
> I certainly think that your idea can work, but in my mind it still
> requires an initial authorization via a Open Dialog. For example,
> imagine a Client that is a file system browser. Initially the Client
> is denied access to a User's data in the SP. The Client requests
> access via the Open Dialog, and the User grants the Client full
> permissions. The Client is then returned a AFL with a URL that points
> to the "top" of the file system--with some content type like HTML or
> Atom or the WebDAV properties type--and the Client can then browse the
> data on the SP.
>
> You could implement your idea and this example with just OAuth, but
> you'd be giving up the explicit control the User gets, which is
> important to me.
I will think about it a bit more, discuss this with my colleagues and then we'll get back to you on this subject.
Anton.
Anton Bar
> No, I didn't mean to require a predefined list. Please read again, I
> proposed "MUST... predefined list OR enter URL...", so it actually gives
> Clients two options and hence more freedom than your proposal.
I get confused reading a MUST with an OR :)
I think it is important that the User always be able to enter a URL,
so the predefined list becomes a recommendation to me. I don't want
to prevent a predefined list but I'd like to keep the requirements
minimal.
.. Adam
Adam Rosien
> proposed "MUST... predefined list OR enter URL...", so it actually gives
> Clients two options and hence more freedom than your proposal.
I get confused reading a MUST with an OR :)
I think it is important that the User always be able to enter a URL,
so the predefined list becomes a recommendation to me. I don't want
Anton Bar
Adam Rosien
Service Providers will be able to serve all Clients, by definition.
If the Client wants to also show a list of preferred or relevant
providers, I think that's a good thing and I support it. But I don't
agree with taking away the user's ability to choose a different
provider.
.. Adam