Proper template for API

[tobiasKaminsky]

Currently API documentation is sometimes missing, sometimes not complete.
I suggest, that we have a template for this and that whenever a new feature is developed, at least API documentation is a part of this.

So here is my rough idea:

Dummy API

short description with ToC, relative links within this md file.

Base URL

Base URL: https://<nextcloud-server>/ocs/v2.php/apps/dummy/api/v1

First command, e.g. "Store xy"

POST: <base-url>/store

Data:

parameter: first parameter

Results:

200 OK: private key stored successfully
400 bad request: unpredictable internal error

Response body on success

<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>200</statuscode>
  <message>OK</message>
 </meta>
 <data>
  <id>123</id>
 </data>
</ocs>

Example curl call:

curl -X POST https://<user>:<password>@<nextcloud-server>/ocs/v2.php/apps/dummy/api/v1/store -d parameter="<first value>" -H "OCS-APIRequest:true"

@blizzz for comments API
@rullzer for Trashbin/versions API