[Owncloud] ownCloud API

Tue Jun 26 15:51:49 UTC 2012

On Tuesday, June 26, 2012 05:42:20 PM Robin Appelman wrote:
> On Tuesday 26 June 2012 11:30:23 Michael Gapczynski wrote:
> > On Tuesday, June 26, 2012 05:22:25 PM Georg Ehrke wrote:
> > > Am 26.06.2012 um 17:17 schrieb Tom Needham:
> > > > On 26 Jun 2012, at 16:06, Michael Gapczynski wrote:
> > > >> We've briefly discussed the implementation of a REST API for
> > > >> ownCloud,
> > > >> but
> > > >> haven't formed any distinct plans for it. I believe we need to set
> > > >> something in place now so developers can start using it and have some
> > > >> nice
> > > >> desktop and mobile integration for the next release. Besides desktop
> > > >> and
> > > >> mobile clients, two Google Summer of Code students also require an
> > > >> API
> > > >> to
> > > >> complete their projects.
> > > >> 
> > > >> What we need is a REST API that can handle user authentication and
> > > >> ownCloud
> > > >> instance to instance communication. My idea is that the API is
> > > >> defined
> > > >> by
> > > >> the apps, in which they register actions and requests for the API to
> > > >> listen to. The API will handle the authentication and pass on the
> > > >> actions and requests back to the apps. To ensure a stable API, I
> > > >> believe
> > > >> that actions and requests should be defined in appinfo/info.xml and
> > > >> registered when the app is enabled.
> > > >> 
> > > >> An example of an action to revert a file back to a previous version:
> > > >> 
> > > >> files_versions/appinfo/info.xml:
> > > >> <api>
> > > >> 
> > > >> 	<action>
> > > >> 	
> > > >> 		<name>revert</name>
> > > >> 		<parameter>
> > > >> 		
> > > >> 			<type>string</type>
> > > >> 			<name>file</name>
> > > >> 		
> > > >> 		</parameter>
> > > >> 		<parameter>
> > > >> 		
> > > >> 			<type>int</type>
> > > >> 			<name>revision</name>
> > > >> 		
> > > >> 		</parameter>
> > > >> 		<class>OCA_Versions</class>
> > > >> 		<function>rollback</function>
> > > >> 	
> > > >> 	</action>
> > > >> 
> > > >> </api>
> > > >> 
> > > >> The call to the action by a client using the API:
> > > >> POST API/action/revert/
> > > >> file:test.txt
> > > >> revision:1340670981
> > > > 
> > > > Should we include the app name in the url, for example, POST
> > > > API/files_versions/action/revert. Otherwise, what happens if two apps
> > > > register the same action? Or is it your intention that we do auth with
> > > > OAuth and so the API will know what app is communicating with it?>
> > > > 
> > > >> An example of a request to retrieve the recent versions of a file:
> > > >> 
> > > >> files_versions/appinfo/info.xml:
> > > >> <api>
> > > >> 
> > > >> 	<request>
> > > >> 	
> > > >> 		<name>versions</name>
> > > >> 		<parameter>
> > > >> 		
> > > >> 			<type>string</type>
> > > >> 			<name>file</name>
> > > >> 		
> > > >> 		</parameter>
> > > >> 		<class>OCA_Versions</class>
> > > >> 		<function>getVersions</function>
> > > >> 	
> > > >> 	</request>
> > > >> 
> > > >> </api>
> > > >> 
> > > >> The call to the request by a client using the API:
> > > >> GET API/request/versions?file=test.txt
> > > > 
> > > > Likewise for this URL obviously.
> > > > 
> > > >> Returns XML or JSON
> > > 
> > > JSON might be the best solution. Just call json_decode and you got an
> > > easy
> > > to handle array.
> > > 
> > > >> The API would also need to handle returning the proper http status
> > > >> codes
> > > >> and converting the data into XML or JSON.
> > > >> 
> > > >> Our options are to create a REST API as part of remote.php (or a
> > > >> different
> > > >> location such as api.php) that can handle authentication of users or
> > > >> extend
> > > >> the Open Collaboration Services (OCS) API written by Frank. I'm
> > > >> thinking
> > > >> that we shouldn't go through OCS in order to avoid confusion about
> > > >> what
> > > >> the API actually is.
> > > > 
> > > > Yes I'd say api.php would be most logical and least confusing.
> > > 
> > > I totally agree to a separated api.php.
> > > What is about OAuth (2) for authentication?
> > 
> > I initially was thinking of using OAuth, but I'm not so sure anymore.
> > WebDAV uses username, password and this API will not replace WebDAV. If
> > we use OAuth for authentication the official mobile apps would need the
> > username and password for WebDAV access and also go through OAuth for the
> > API. This seems like too much work for me.
> > 
> > I would prefer if official apps could just use username, password
> > authentication and any 3rd party be forced to use OAuth. I'm not sure how
> > to do this though without a 3rd party going through the same route as an
> > official app.
> 
> We can mix OAuth and user/password, once we have a user backend for OAuth
> you can use OAuth for the existing *DAV's if you want and use it for any
> API provided by apps.
> The same way you can decide to just use user/password auth for the api, the
> only real difference between both ways is that OAuth limits you to a scope
> (e.g. only the calendar)

Is there a way to force 3rd party apps to use OAuth authentication? No one 
wants to use OAuth if they can just ask the user for their username and 
password. 

> 
> > > >> Please share your thoughts.
> > > >> 
> > > >> 
> > > >> Michael
> > > >> _______________________________________________
> > > >> Owncloud mailing list
> > > >> Owncloud at kde.org
> > > >> https://mail.kde.org/mailman/listinfo/owncloud
> > > > 
> > > > _______________________________________________
> > > > Owncloud mailing list
> > > > Owncloud at kde.org
> > > > https://mail.kde.org/mailman/listinfo/owncloud
> > > 
> > > _______________________________________________
> > > Owncloud mailing list
> > > Owncloud at kde.org
> > > https://mail.kde.org/mailman/listinfo/owncloud
> > 
> > _______________________________________________
> > Owncloud mailing list
> > Owncloud at kde.org
> > https://mail.kde.org/mailman/listinfo/owncloud
> 
>  - Robin Appelman