developer workflow docs

docs/restapi.rst

@@ -3,8 +3,47 @@ REST API
 
 A REST API for publishing and deleting app releases has been built into the store from day one to help release automation.
 
-TODO: talk about rest usage workflow
+Intended Developer Workflow
+---------------------------
 
+Most of today's developers publish their source code on GitHub, BitBucket or on their own GitLab instance. These tools typically also provide a way to release new versions based on Git tags or by uploading custom archives.
+
+Advanced users and developers typically prefer to download the app directly from these services whereas administrators or novice users look for app releases on the app store. This means that you have to take care of publishing two releases on two different platforms.
+
+We want to avoid duplication and make it harder to ship broken releases by mistake, therefore we went for the following solution:
+
+* Your app's source code is hosted on GitHub or a similar service
+
+* You should use Git tags to create new releases on these services
+
+* Archives are typically created automatically for you. If you require compilation or other transformations like minification, you should upload a pre-built archive to the appropriate releases page
+
+This keeps your repository up to date and satisfies the needs of developers and advanced users.
+
+To publish an app release on the app store you simply send us a download link for the release archive. We then do the following:
+
+* Your archive is downloaded from the given location. This ensures that your users don't hit dead links. If your archive is too big, we will abort the download.
+
+* The archive is then extracted and the package structure is validated:
+
+ * The archive most only contain one top level folder consisting of lower case ASCII characters and underscores
+ * The archive must contain an **info.xml** file inside the **appinfo** directory which in turn is located in the top folder
+
+* The app's metadata is then extracted from the **info.xml** file and validated using an XML Schema (available under `https://apps.nextcloud.com/info.xsd <https://apps.nextcloud.com/info.xsd>`_):
+
+ * The app folder must match the id
+ * The specified versions must have 1 to 3 digits separated by dots
+ * The XML elements must contain valid content (e.g. known categories and enumerations)
+
+* The release is then either created or updated. The downloaded archive will be deleted
+
+Since this implies that the download location must be trusted, the following mechanisms are in place to guarantee that the downloaded version has not been tampered with:
+
+* You can submit a sha256sum hash in addition to the download link. The hash is validated before a user wants to install it. If you omit the hash, we generate it from the downloaded archive
+
+* You can sign your code `using a certificate <https://docs.nextcloud.org/server/9/developer_manual/app/code_signing.html>`_
+
+* You must supply an HTTPS download url for the archive
 
 Specification
 -------------
@@ -98,10 +137,10 @@ This route will return all releases to display inside Nextcloud's apps admin are
                 }
             ],
             "licenses": [
-                          {
-                              "id": "agpl",
-                              "name": "AGPLv3+"
-                          }
+                  {
+                      "id": "agpl",
+                      "name": "AGPLv3+"
+                  }
             ],
             "screenshots": [
                 {
@@ -125,16 +164,19 @@ translations
     Translated fields are stored inside a translations object. They can have any size, depending on if there is a translation. If a required language is not found, you should fall back to English.
 
 versionSpec
-    Required versions (minimum and maximum versions) are transformed to semantic version specs. If a field is a *, this means that there is no version requirement. The following permutations can occur:
+    Required versions (minimum and maximum versions) are transformed to semantic version specs. If a field is a \*, this means that there is no version requirement. The following permutations can occur:
 
-     * **All versions**: *
+     * **All versions**: \*
      * **Maximum version only**: <8.1.2
      * **Minimum version only**: >=9.3.2
      * **Maximum and minimum version**: >=9.3.2 <8.1.2
 
 checksum
     The checksum is generated by running sha256sum over the downloaded archive.
 
+recommendations
+    Who many users recommend the app
+
 .. _api-delete-app:
 
 Delete an App
@@ -151,6 +193,8 @@ Deleting an app will also delete all releases which are associated with it.
 
 * **Authentication**: Basic
 
+* **Authorization**: App owners
+
 * **Example CURL request**::
 
     curl -X DELETE http://localhost:8000/api/v1/apps/news -u "user:password"
@@ -159,9 +203,9 @@ Deleting an app will also delete all releases which are associated with it.
 * **Returns**:
 
  * **HTTP 204**: If the app was deleted successfully
- * **HTTP 400**: If the app could not be found
  * **HTTP 401**: If the user is not authenticated
  * **HTTP 403**: If the user is not authorized to delete the app
+ * **HTTP 404**: If the app could not be found
 
 .. _api-delete-release:
 
@@ -178,6 +222,8 @@ Only app owners or co-maintainers are allowed to delete an app release. The owne
 
 * **Authentication**: Basic
 
+* **Authorization**: App owners and co-maintainers
+
 * **Example CURL request**::
 
     curl -X DELETE http://localhost:8000/api/v1/apps/news/releases/9.0.0 -u "user:password"
@@ -186,15 +232,15 @@ Only app owners or co-maintainers are allowed to delete an app release. The owne
 * **Returns**:
 
   * **HTTP 204**: If the app release was deleted successfully
-  * **HTTP 400**: If the app release could not be found
   * **HTTP 401**: If the user is not authenticated
   * **HTTP 403**: If the user is not authorized to delete the app release
+  * **HTTP 404**: If the app release could not be found
 
 
 .. _api-create-release:
 
-Release or Update a New App Release
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Publish a New App Release
+~~~~~~~~~~~~~~~~~~~~~~~~~
 The following request will create a new app release:
 
 * **Url**: POST /api/v1/apps/releases