<commit_before># API (v1)
This is a draft and will continuously be updated :)


## Get All Apps And Their Releases For a Platform Release
This is the route that will return all releases to display inside Nextcloud's apps admin area. Future releases will add Http caching.

* **Url**: GET /api/v1/platform/{platform-version}/apps.json
  * **Parameters**:
    * **platform-version**: semantic version, digits only: Returns all the apps and their releases that work on this version. If an app has no working releases, the app will be excluded
* **Example CURL request**:

        curl http://localhost:8000/api/v1/platform/9.0.0/apps.json

* **Authentication**: None

* **Returns**: application/json
    ```json
    [
        {
            "id": "news",
            "categories": [
                {
                    "id": "tools",
                    "translations": {
                        "en": {
                            "name": "Tools"
                        },
                        "de": {
                            "name": "Werkzeuge"
                        },
                        "fr": {
                            "name": "Outil"
                        }
                    }
                }
            ],
            "recommendations": 100,
            "userDocs": "http://127.0.0.1:8000/user",
            "adminDocs": "http://127.0.0.1:8000/admin",
            "developerDocs": "http://127.0.0.1:8000/dev",
            "issueTracker": "http://127.0.0.1:8000/issue",
            "website": "http://127.0.0.1:8000/",
            "created": "2016-06-09T17:56:05.076980Z",
            "lastModified": "2016-06-09T17:56:19.099038Z",
            "releases": [
                {
                    "version": "1.9.0",
                    "checksum": "65e613318107bceb131af5cf8b71e773b79e1a9476506f502c8e2017b52aba15",
                    "libs": [
                        {
                            "id": "libxml",
                            "minVersion": "3",
                            "maxVersion": "4"
                        }
                    ],
                    "databases": [
                        {
                            "id": "sqlite",
                            "name": "Sqlite",
                            "minVersion": "1",
                            "maxVersion": "2"
                        }
                    ],
                    "shellCommands": [
                        "grep"
                    ],
                    "phpMinVersion": "5.6",
                    "phpMaxVersion": "",
                    "platformMinVersion": "9.0",
                    "platformMaxVersion": "",
                    "minIntSize": 64,
                    "download": "https://127.0.0.1:8000/download",
                    "created": "2016-06-09T17:57:00.587076Z",
                    "lastModified": "2016-06-09T17:57:00.587238Z"
                }
            ],
            "licenses": [
                          {
                              "id": "agpl",
                              "name": "AGPLv3+"
                          }
            ],
            "screenshots": [
                {
                    "url": "http://feeds2.feedburner.com/blogerator"
                }
            ],
            "translations": {
                "en": {
                    "name": "News",
                    "description": "Read News"
                },
                "de": {
                    "name": "Neuigkeiten",
                    "description": "Nachrichten lesen"
                }
            }
        }
    ]
    ```

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.

Required versions (minimum and maximum versions) are stored in String fields. If a field is empty, this means that there is no version requirement. Minimum and maximum versions are inclusive, e.g. if your app works only on PHP 5.5 and 5.6, the minimum version will be 5.5.0 while the maximum version will be 5.6.*

The checksum is generate using the archive via sha256sum

## Delete An App
Only app owners are allowed to delete an app. The owner is the user that pushes the first release of an app to the store.

Deleting an app will also delete all releases which are associated with it.

* **Url**: DELETE /api/v1/apps/{app-id}
  * **Parameters**:
    * **app-id**: app id, lower case ASCII characters and underscores are allowed
* **Example CURL request**:

        curl -X DELETE http://localhost:8000/api/v1/apps/news

* **Authentication**: Basic

* **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

## Delete An App Release
Only app owners or co-maintainers are allowed to delete an app release. The owner is the user that pushes the first release of an app to the store.

* **Url**: DELETE /api/v1/apps/{app-id}/releases/{app-version}
  * **Parameters**:
    * **app-id**: app id, lower case ASCII characters and underscores are allowed
    * **app-version**: app version, semantic version, digits only
* **Example CURL request**:

        curl -X DELETE http://localhost:8000/api/v1/apps/news/releases/9.0.0

* **Authentication**: Basic

* **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


## Release a New App Release Or Update an Existing One
The following request will create a new app release:

* **Url**: PUT /api/v1/apps/{app-id}/releases/{version}
  * **Parameters**:
    * **app-id**: lowercase ASCII characters and underscores, the app's id
    * **version**: semantic version, digits only: app release version
* **Content-Type**: application/json
* **Request body**:
  * **download**: An Https (Http is not allowed!) link to the archive packaged (maximum size: 50 Megabytes) as tar.gz:

  ```json
  {"download":"https://example.com/release.tar.gz"}
  ```

* **Example CURL request**:

        curl -X PUT -u "user:password" http://localhost:8000/api/v1/apps/news/releases -H "Content-Type: application/json" -d '{"download":"https://example.com/release.tar.gz"}'

* **Returns**:
  * **HTTP 200**: If the app release was update successfully
  * **HTTP 201**: If the app release was created successfully
  * **HTTP 400**: If the app contains invalid data, is too large or could not be downloaded
  * **HTTP 401**: If the user is not authenticated
  * **HTTP 403**: If the user is not authorized to delete the app release

If there is not yet an app with the given app id yet, a new app is created and the owner is set in to the logged in user. Then the **info.xml** file which lies in the compressed archive's folder **app-id/appinfo/info.xml** is being parsed and validated.

Afterwards the app and app release will be created or updated, depending on if they already exist. Both owners and co-maintainers are allowed to upload new releases.

A minimum valid **info.xml** would look like this:
```xml<commit_msg>restruct<commit_after># API (v1)
This is a draft and will continuously be updated :)


## Get All Apps And Their Releases For a Platform Release
This is the route that will return all releases to display inside Nextcloud's apps admin area. Future releases will add Http caching.

* **Url**: GET /api/v1/platform/{platform-version}/apps.json
  * **Parameters**:
    * **platform-version**: semantic version, digits only: Returns all the apps and their releases that work on this version. If an app has no working releases, the app will be excluded
* **Example CURL request**:

        curl http://localhost:8000/api/v1/platform/9.0.0/apps.json

* **Authentication**: None

* **Returns**: application/json
    ```json
    [
        {
            "id": "news",
            "categories": [
                {
                    "id": "tools",
                    "translations": {
                        "en": {
                            "name": "Tools"
                        },
                        "de": {
                            "name": "Werkzeuge"
                        },
                        "fr": {
                            "name": "Outil"
                        }
                    }
                }
            ],
            "recommendations": 100,
            "userDocs": "http://127.0.0.1:8000/user",
            "adminDocs": "http://127.0.0.1:8000/admin",
            "developerDocs": "http://127.0.0.1:8000/dev",
            "issueTracker": "http://127.0.0.1:8000/issue",
            "website": "http://127.0.0.1:8000/",
            "created": "2016-06-09T17:56:05.076980Z",
            "lastModified": "2016-06-09T17:56:19.099038Z",
            "releases": [
                {
                    "version": "1.9.0",
                    "checksum": "65e613318107bceb131af5cf8b71e773b79e1a9476506f502c8e2017b52aba15",
                    "libs": [
                        {
                            "id": "libxml",
                            "minVersion": "3",
                            "maxVersion": "4"
                        }
                    ],
                    "databases": [
                        {
                            "id": "sqlite",
                            "name": "Sqlite",
                            "minVersion": "1",
                            "maxVersion": "2"
                        }
                    ],
                    "shellCommands": [
                        "grep"
                    ],
                    "phpMinVersion": "5.6",
                    "phpMaxVersion": "",
                    "platformMinVersion": "9.0",
                    "platformMaxVersion": "",
                    "minIntSize": 64,
                    "download": "https://127.0.0.1:8000/download",
                    "created": "2016-06-09T17:57:00.587076Z",
                    "lastModified": "2016-06-09T17:57:00.587238Z"
                }
            ],
            "licenses": [
                          {
                              "id": "agpl",
                              "name": "AGPLv3+"
                          }
            ],
            "screenshots": [
                {
                    "url": "http://feeds2.feedburner.com/blogerator"
                }
            ],
            "translations": {
                "en": {
                    "name": "News",
                    "description": "Read News"
                },
                "de": {
                    "name": "Neuigkeiten",
                    "description": "Nachrichten lesen"
                }
            }
        }
    ]
    ```

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.

Required versions (minimum and maximum versions) are stored in String fields. If a field is empty, this means that there is no version requirement. Minimum and maximum versions are inclusive, e.g. if your app works only on PHP 5.5 and 5.6, the minimum version will be 5.5.0 while the maximum version will be 5.6.*

The checksum is generated by running sha256sum over the downloaded archive.

## Delete An App
Only app owners are allowed to delete an app. The owner is the user that pushes the first release of an app to the store.

Deleting an app will also delete all releases which are associated with it.

* **Url**: DELETE /api/v1/apps/{app-id}
  * **Parameters**:
    * **app-id**: app id, lower case ASCII characters and underscores are allowed
* **Example CURL request**:

        curl -X DELETE http://localhost:8000/api/v1/apps/news

* **Authentication**: Basic

* **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

## Delete An App Release
Only app owners or co-maintainers are allowed to delete an app release. The owner is the user that pushes the first release of an app to the store.

* **Url**: DELETE /api/v1/apps/{app-id}/releases/{app-version}
  * **Parameters**:
    * **app-id**: app id, lower case ASCII characters and underscores are allowed
    * **app-version**: app version, semantic version, digits only
* **Example CURL request**:

        curl -X DELETE http://localhost:8000/api/v1/apps/news/releases/9.0.0

* **Authentication**: Basic

* **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


## Release a New App Release Or Update an Existing One
The following request will create a new app release:

* **Url**: PUT /api/v1/apps/{app-id}/releases/{version}
  * **Parameters**:
    * **app-id**: lowercase ASCII characters and underscores, the app's id
    * **version**: semantic version, digits only: app release version
* **Content-Type**: application/json
* **Request body**:
  * **download**: An Https (Http is not allowed!) link to the archive packaged (maximum size: 50 Megabytes) as tar.gz:

  ```json
  {"download":"https://example.com/release.tar.gz"}
  ```

* **Example CURL request**:

        curl -X PUT -u "user:password" http://localhost:8000/api/v1/apps/news/releases -H "Content-Type: application/json" -d '{"download":"https://example.com/release.tar.gz"}'

* **Returns**:
  * **HTTP 200**: If the app release was update successfully
  * **HTTP 201**: If the app release was created successfully
  * **HTTP 400**: If the app contains invalid data, is too large or could not be downloaded
  * **HTTP 401**: If the user is not authenticated
  * **HTTP 403**: If the user is not authorized to delete the app release

If there is no app with the given app id yet, a new app is created and the owner is set in to the logged in user. Then the **info.xml** file which lies in the compressed archive's folder **app-id/appinfo/info.xml** is being parsed and validated. The validated result is then saved in the database. Both owners and co-maintainers are allowed to upload new releases.

A minimum valid **info.xml** would look like this:
```xml
{'fraction_non_alphanumeric': 0.11981883063409278, 'fraction_numerical': 0.039116113093604174, 'mean_word_length': 1.752219074598678, 'pattern_counts': {'":': 106, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 10}, 'pii_count': 12, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 13, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5764475', 'n_tokens_mistral': 4339, 'n_tokens_neox': 3796, 'n_words': 1381}