[Owncloud] ownCloud API

[Robin Appelman]

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)

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