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
_______________________________________________
Owncloud mailing list
[email protected]
https://mail.kde.org/mailman/listinfo/owncloud
