[Owncloud] ownCloud API

[Klaas Freitag]

On 26.06.2012 17:17, Tom Needham wrote:
> 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
I like this general idea as this sounds like we can export a whole bunch 
of functionality with a couple of XML scripts. Cool.

I don't want to nitpick or start something big on this, however we 
should be aware of the fact that this is probably not a REST API, but 
rather an exported ownCloud API.

A REST API is a resource based API with a couple of concepts behind [1].
To do the example above REST conform, you could for example POST a 
'revert order' in XML on the document, ie.

POST "<file="test.txt"><date ../><reason../></file>" => API/files/reverts

A GET on API/files/reverts will give a list of all reverts done etc. pp.

I am not saying we should to do it this way, yet it makes a difference. 
And we should think once in a while if we're REST conform or not. Maybe 
calling 'it' the 'ownCloud Exported API' OCEA is also fine.

Two other questions with your proposal:
- How do we do error handling?
- Can/do we need more complex parameters passed to the functions, like 
arrays at least? Maybe we can find a standard for this?

What do you think?

Klaas