[Owncloud] ownCloud API

[Tom Needham]

On 26 Jun 2012, at 16:30, 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 have been looking at getting the official mobile apps to connect to ownCloud using QR codes so there is no need for typing. I need to read more into OAuth but I think we could send the token through the QR code and save the user having to type in anything.

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