[Owncloud] ownCloud API

[Michael Gapczynski]

There is no standard for a RESTful web API, but this does meet the general 
expectations. Not all REST APIs that I've encountered require you to 
communicate using XML, but some just use POST parameters. I think POST 
parameters are always easier than generating XML. Then again, I'm not quite 
sure what an 'exported' API is. 

Error handling might be tricky, but I believe we could define some general 
errors that the API handling functions within the apps could return so we can 
pass on the correct HTTP status codes.

I'm not sure why you would need an array, when you can just add additional 
parameters. We'll have to have a standard for optional parameters.

Now I'm concerned about how to store/retrieve these API actions and requests. 
Reading the files isn't very efficient and it's tricky to store something like 
this in the database with an unknown number of parameters. My initial thought 
was that defining them in info.xml was better than a function call to register 
with the API because it would encourage a stable API. 

I'm still waiting to hear from Frank about the advantages of just extending 
OCS, but I still think this is the best 'backend' for the API. 


Michael


On Thursday, June 28, 2012 01:28:05 PM Jörn Friedrich Dreyer wrote:
> Klaas, you have my support on the REST conformity. Doing REST right is
> harder than a simple AJAX API.
> 
> Am 28.06.2012 11:34 schrieb "Klaas Freitag" <freitag at owncloud.com>:
> > On 26.06.2012 17:17, Tom Needham wrote:
> >> On 26 Jun 2012, at 16:06, Michael Gapczynski wrote:
> >>> 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.
> In a real REST API authentication is handled by HTTP (and then via tokens).
> 
> > 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.
> +1
> 
> > 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?
> 
> In REST we would use HTTP error codes, maybe with json/xml content.
> 
> > - Can/do we need more complex parameters passed to the functions, like
> 
> arrays at least? Maybe we can find a standard for this?
> Well ... shouldn't that be done with POST requests and xml/json payload?
> 
> So long
> 
> Jörn