[Owncloud] ownCloud API

[Michael Gapczynski]

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


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

Returns XML or JSON


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. 

Please share your thoughts.


Michael