From e0a92c6455480edda419f7b85e1d5a6d09840b4e Mon Sep 17 00:00:00 2001
From: rubenwardy <rw@rubenwardy.com>
Date: Wed, 12 Jan 2022 17:08:18 +0000
Subject: [PATCH] Add /api/dependencies/

---
 app/blueprints/api/endpoints.py | 32 ++++++++++++++++++++++++++
 app/flatpages/help/api.md       | 40 +++++++++++++++++++++++++++------
 2 files changed, 65 insertions(+), 7 deletions(-)

diff --git a/app/blueprints/api/endpoints.py b/app/blueprints/api/endpoints.py
index a433851d..462871b9 100644
--- a/app/blueprints/api/endpoints.py
+++ b/app/blueprints/api/endpoints.py
@@ -491,3 +491,35 @@ def versions():
 
 	return jsonify([rel.getAsDictionary() \
 			for rel in MinetestRelease.query.all() if rel.getActual() is not None])
+
+
+@bp.route("/api/dependencies/")
+@cors_allowed
+def all_deps():
+	qb = QueryBuilder(request.args)
+	query = qb.buildPackageQuery()
+
+	def format_pkg(pkg: Package):
+		return {
+			"type": pkg.type.toName(),
+			"author": pkg.author.username,
+			"name": pkg.name,
+			"provides": [x.name for x in pkg.provides],
+			"depends": [str(x) for x in pkg.dependencies if not x.optional],
+			"optional_depends": [str(x) for x in pkg.dependencies if x.optional],
+		}
+
+	page = get_int_or_abort(request.args.get("page"), 1)
+	num = min(get_int_or_abort(request.args.get("n"), 100), 100)
+	pagination: flask_sqlalchemy.Pagination = query.paginate(page, num, True)
+	return jsonify({
+		"page": pagination.page,
+		"per_page": pagination.per_page,
+		"page_count": math.ceil(pagination.total / pagination.per_page),
+		"total": pagination.total,
+		"urls": {
+			"previous": abs_url(url_set_query(page=page - 1)) if pagination.has_prev else None,
+			"next": abs_url(url_set_query(page=page + 1)) if pagination.has_next else None,
+		},
+		"items": [format_pkg(pkg) for pkg in pagination.items],
+	})
diff --git a/app/flatpages/help/api.md b/app/flatpages/help/api.md
index c279b265..e2ff3113 100644
--- a/app/flatpages/help/api.md
+++ b/app/flatpages/help/api.md
@@ -32,6 +32,23 @@ often other keys with information. For example:
 ```
 
 
+### Paginated Results
+
+Some API endpoints returns results in pages. The page number is specified using the `page` query argument, and
+the number of items is specified using `num`
+
+The response will be a dictionary with the following keys:
+
+* `page`: page number, integer from 1 to max 
+* `per_page`: number of items per page, same as `n`
+* `page_count`: number of pages
+* `total`: total number of results
+* `urls`: dictionary containing
+    * `next`: url to next page
+    * `previous`: url to previous page
+* `items`: array of items
+
+
 ## Authentication
 
 Not all endpoints require authentication, but it is done using Bearer tokens:
@@ -73,7 +90,22 @@ Tokens can be attained by visiting [Settings > API Tokens](/user/tokens/).
         * `issue_tracker`: Issue tracker URL.
         * `forums`: forum topic ID.
 * GET `/api/packages/<username>/<name>/dependencies/`
+    * Returns dependencies, with suggested candidates 
     * If query argument `only_hard` is present, only hard deps will be returned.
+* GET `/api/dependencies/`
+    * Returns `provides` and raw dependencies for all packages.
+    * Supports [Package Queries](#package-queries)
+    * [Paginated result](#paginated-results), max 100 results per page
+    * Each item in `items` will be a dictionary with the following keys:
+        * `type`: One of `GAME`, `MOD`, `TXP`. 
+        * `author`: Username of the package author.
+        * `name`: Package name.
+        * `provides`: List of technical mod names inside the package.
+        * `depends`: List of hard dependencies.
+            * Each dep will either be a metapackage dependency (`name`), or a
+                package dependency (`author/name`).
+        * `optional_depends`: list of optional dependencies
+            * Same as above.
 
 You can download a package by building one of the two URLs:
 
@@ -240,13 +272,7 @@ curl -X POST https://content.minetest.net/api/packages/username/name/screenshots
         * `votes`: dictionary with `helpful` and `unhelpful`,
 * GET `/api/reviews/` (List)
     * Returns a paginated response. This is a dictionary with `page`, `url`, and `items`.
-        * `page`: page number, integer from 1 to max
-        * `per_page`: number of items per page, same as `n`
-        * `page_count`: number of pages
-        * `total`: total number of results
-        * `urls`: dictionary containing
-            * `next`: url to next page
-            * `previous`: url to previous page
+        * [Paginated result](#paginated-results)
         * `items`: array of review dictionaries, like above
             * Each review also has a `package` dictionary with `type`, `author` and `name`
     * Query arguments: