[Owncloud] ownCloud API

[Michael Gapczynski]

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.

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