[Owncloud] ownCloud API

[Michael Gapczynski]

On Tuesday, June 26, 2012 04:17:37 PM 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
> 
> 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?

That would probably make more sense to construct the urls.

> > 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
> > 
> > 
> > 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.
> 
> > Please share your thoughts.
> > 
> > 
> > Michael
> > _______________________________________________
> > Owncloud mailing list
> > Owncloud at kde.org
> > https://mail.kde.org/mailman/listinfo/owncloud