dspace_statistics_api/docs/openapi.json: Minor edit

Better to leave the version in there because Swagger Editor doesn't like it without. Also, change the example page parameter for POSTing to /items and /collections, as it doesn't make sense to start on a later page if we have less items than our limit.
Move unreleased change to v1.4.0
2025-09-08 04:41:49 +02:00 · 2020-12-27 13:53:59 +02:00 · 2020-12-27 12:52:24 +02:00 · 2020-12-27 12:48:13 +02:00 · 2020-12-27 12:27:01 +02:00 · 2020-12-27 12:26:32 +02:00
14 changed files with 56 additions and 66 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

-## Unreleased
+## [1.4.0] - 2020-12-27
 ### Added
 - indexer.py now indexes views and downloads for communities and collections
 - API endpoints for /communities, /community/id, /collections, and /collections/id
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 deterministically
 - Use `fl` parameter in indexer to return only the field we are faceting by
 - Minor refactoring of imports for PEP8 style
+- More correct calculation of `totalPages` parameter in REST API response

 ## [1.3.2] - 2020-11-18
 ### Fixed
--- a/dspace_statistics_api/app.py
+++ b/dspace_statistics_api/app.py
@@ -1,4 +1,5 @@
 import json
+import math

 import falcon
 import psycopg2.extras
@@ -14,8 +15,21 @@ class RootResource:
    def on_get(self, req, resp):
        resp.status = falcon.HTTP_200
        resp.content_type = "text/html"
-        with open("dspace_statistics_api/docs/index.html", "r") as f:
-            resp.body = f.read()
+        docs_html = (
+            "<!DOCTYPE html>"
+            '<html lang="en-US">'
+            "    <head>"
+            '        <meta charset="UTF-8">'
+            "        <title>DSpace Statistics API</title>"
+            "    </head>"
+            "    <body>"
+            f"        <h1>DSpace Statistics API {VERSION}</h1>"
+            f"        <p>This site is running the <a href=\"https://github.com/ilri/dspace-statistics-api\" title=\"DSpace Statistics API project\">DSpace Statistics API</a>. For more information see the project's README.md or the interactive <a href=\"{DSPACE_STATISTICS_API_URL + '/swagger'}\">Swagger UI</a> built into this API.</p>"
+            "    </body>"
+            "</html"
+        )
+
+        resp.body = docs_html


 class StatusResource:
@@ -44,6 +58,9 @@ class OpenAPIJSONResource:
            if DSPACE_STATISTICS_API_URL != "":
                data["servers"] = [{"url": DSPACE_STATISTICS_API_URL}]

+            # Set the version in the schema so Swagger UI can display it
+            data["info"]["version"] = VERSION
+
            resp.body = json.dumps(data)


@@ -62,7 +79,7 @@ class AllStatisticsResource:
            with db.cursor() as cursor:
                # get total number of communities/collections/items so we can estimate the pages
                cursor.execute(f"SELECT COUNT(id) FROM {req.context.statistics_scope}")
-                pages = round(cursor.fetchone()[0] / limit)
+                pages = math.ceil(cursor.fetchone()[0] / limit)

                # get statistics and use limit and offset to page through results
                cursor.execute(
@@ -115,7 +132,7 @@ class AllStatisticsResource:
        # Helper variables to make working with pages/items/results easier and
        # to make the code easier to understand
        number_of_elements: int = len(req.context.elements)
-        pages: int = int(number_of_elements / req.context.limit)
+        pages: int = math.ceil(number_of_elements / req.context.limit)
        first_element: int = req.context.page * req.context.limit
        last_element: int = first_element + req.context.limit
        # Get a subset of the POSTed items based on our limit. Note that Python
--- a/dspace_statistics_api/config.py
+++ b/dspace_statistics_api/config.py
@@ -16,6 +16,6 @@ DATABASE_PORT = os.environ.get("DATABASE_PORT", "5432")
 # the vanilla DSpace REST API.
 DSPACE_STATISTICS_API_URL = os.environ.get("DSPACE_STATISTICS_API_URL", "")

-VERSION = "1.4.0-dev"
+VERSION = "1.4.0"

 # vim: set sw=4 ts=4 expandtab:
--- a/dspace_statistics_api/docs/index.html
+++ b/dspace_statistics_api/docs/index.html
@@ -1,44 +0,0 @@
-<!DOCTYPE html>
-<html lang="en-US">
-    <head>
-        <meta charset="UTF-8">
-        <title>DSpace Statistics API</title>
-    </head>
-    <body>
-        <h1>DSpace Statistics API v1.4.0-dev</h1>
-        <p>This site is running the <a href="https://github.com/ilri/dspace-statistics-api" title="DSpace Statistics API project">DSpace Statistics API</a>. The following endpoints are available:</p>
-        <ul>
-            <li>GET <code>/</code> — return a basic API documentation page.</li>
-            <li>GET <code>/items</code> — return views and downloads for all items that Solr knows about¹. Accepts <code>limit</code> and <code>page</code> query parameters for pagination of results (<code>limit</code> must be an integer between 1 and 100, and <code>page</code> must be an integer greater than or equal to 0).</li>
-            <li>POST <code>/items</code> — return views and downloads for an arbitrary list of items with an optional date range. Accepts <code>limit</code>, <code>page</code>, <code>dateFrom</code>, and <code>dateTo</code> parameters².</li>
-            <li>GET <code>/item/id</code> — return views and downloads for a single item (<code>id</code> must be a UUID). Returns HTTP 404 if an item id is not found.</li>
-            <li>GET <code>/communities</code> — return views and downloads for all communities that Solr knows about¹. Accepts <code>limit</code> and <code>page</code> query parameters for pagination of results (<code>limit</code> must be an integer between 1 and 100, and <code>page</code> must be an integer greater than or equal to 0).
-            <li>POST <code>/communities</code> — return views and downloads for an arbitrary list of communities with an optional date range. Accepts <code>limit</code>, <code>page</code>, <code>dateFrom</code>, and <code>dateTo</code> parameters².
-            <li>GET <code>/community/id</code> — return views and downloads for a single community (<code>id</code> must be a UUID). Returns HTTP 404 if a community id is not found.
-            <li>GET <code>/collections</code> — return views and downloads for all collections that Solr knows about¹. Accepts <code>limit</code> and <code>page</code> query parameters for pagination of results (<code>limit</code> must be an integer between 1 and 100, and <code>page</code> must be an integer greater than or equal to 0).
-            <li>POST <code>/collections</code> — return views and downloads for an arbitrary list of collections with an optional date range. Accepts <code>limit</code>, <code>page</code>, <code>dateFrom</code>, and <code>dateTo</code> parameters².
-            <li>GET <code>/collection/id</code> — return views and downloads for a single collection (<code>id</code> must be a UUID). Returns HTTP 404 if an collection id is not found.
-        </ul>
-
-        <p>The id is the <em>internal</em> UUID for an item, community, or collection. You can get these from the standard DSpace REST API.</p>
-
-        <hr/>
-
-        <p>¹ We are querying the Solr statistics core, which technically only knows about items, communities, or collections that have either views or downloads. If an item, community, or collection is not present here you can assume it has zero views and zero downloads, but not necessarily that it does not exist in the repository.</p>
-
-        <p>² POST requests to <code>/items</code>, <code>/communities</code>, and <code>/collections</code> should be in JSON format with the following parameters (substitute the "items" list for communities or collections accordingly):</p>
-			<pre><code>{
-	"limit": 100, // optional, integer between 1 and 100, default 100
-	"page": 0, // optional, integer greater than 0, default 0
-	"dateFrom": "2020-01-01T00:00:00Z", // optional, default *
-	"dateTo": "2020-09-09T00:00:00Z", // optional, default *
-	"items": [
-		"f44cf173-2344-4eb2-8f00-ee55df32c76f",
-		"2324aa41-e9de-4a2b-bc36-16241464683e",
-		"8542f9da-9ce1-4614-abf4-f2e3fdb4b305",
-		"0fe573e7-042a-4240-a4d9-753b61233908"
-	]
-}</code></pre>
-        </p>
-    </body>
-</html>
--- a/dspace_statistics_api/docs/openapi.json
+++ b/dspace_statistics_api/docs/openapi.json
@@ -1,7 +1,7 @@
 {
  "openapi": "3.0.3",
  "info": {
-    "version": "1.4.0-dev",
+    "version": "1.4.0",
    "title": "DSpace Statistics API",
    "description": "A [Falcon-based](https://falcon.readthedocs.io/) web application to make DSpace's item, community, and collection statistics available via a simple REST API. This Swagger interface is powered by [falcon-swagger-ui](https://github.com/rdidyk/falcon-swagger-ui).",
    "license": {
@@ -142,7 +142,7 @@
                },
                "example": {
                  "limit": 100,
-                  "page": 5,
+                  "page": 0,
                  "dateFrom": "2020-01-01T00:00:00Z",
                  "dateTo": "2020-12-31T00:00:00Z",
                  "items": [
@@ -502,7 +502,7 @@
                },
                "example": {
                  "limit": 100,
-                  "page": 2,
+                  "page": 0,
                  "dateFrom": "2020-01-01T00:00:00Z",
                  "dateTo": "2020-12-31T00:00:00Z",
                  "collections": [
--- a/dspace_statistics_api/indexer.py
+++ b/dspace_statistics_api/indexer.py
@@ -28,6 +28,8 @@
 #
 # See: https://wiki.duraspace.org/display/DSPACE/Solr

+import math
+
 import psycopg2.extras
 import requests

@@ -75,9 +77,9 @@ def index_views(indexType: str, facetField: str):

        exit(0)

-    # divide results into "pages" (cast to int to effectively round down)
+    # divide results into "pages" and round up to next integer
    results_per_page = 100
-    results_num_pages = int(results_totalNumFacets / results_per_page)
+    results_num_pages = math.ceil(results_totalNumFacets / results_per_page)
    results_current_page = 0

    with DatabaseManager() as db:
@@ -158,9 +160,8 @@ def index_downloads(indexType: str, facetField: str):

        exit(0)

-    # divide results into "pages" (cast to int to effectively round down)
    results_per_page = 100
-    results_num_pages = int(results_totalNumFacets / results_per_page)
+    results_num_pages = math.ceil(results_totalNumFacets / results_per_page)
    results_current_page = 0

    with DatabaseManager() as db:
--- a/poetry.lock
+++ b/poetry.lock
@@ -144,6 +144,11 @@ python-versions = "*"
 falcon = "*"
 Jinja2 = "*"

+[package.source]
+url = "https://github.com/alanorth/falcon-swagger-ui.git"
+reference = "a44244c85dceccfcd249b62fea4ee82a8221e3d2"
+type = "git"
+
 [[package]]
 name = "flake8"
 version = "3.8.4"
@@ -589,7 +594,7 @@ testing = ["pytest (>=3.5,<3.7.3 || >3.7.3)", "pytest-checkdocs (>=1.2.3)", "pyt
 [metadata]
 lock-version = "1.0"
 python-versions = "^3.6"
-content-hash = "1d56758c9e3aa4586109e8aaf4def576d3506385bc749b97e8518f936f2e91ca"
+content-hash = "3a8e8a7152971ae091864e7dd5a8fd25f895f68dd1444bffc153c61227e84914"

 [metadata.files]
 appdirs = [
@@ -655,9 +660,7 @@ falcon = [
    {file = "falcon-2.0.0-py2.py3-none-any.whl", hash = "sha256:54f2cb4b687035b2a03206dbfc538055cc48b59a953187b0458aa1b574d47b53"},
    {file = "falcon-2.0.0.tar.gz", hash = "sha256:eea593cf466b9c126ce667f6d30503624ef24459f118c75594a69353b6c3d5fc"},
 ]
-falcon-swagger-ui = [
-    {file = "falcon_swagger_ui-1.2.1-py3-none-any.whl", hash = "sha256:2514e6cb403e87e49a1527764cf090c82885185cc650b7ab5cefa8ebe89af8b8"},
-]
+falcon-swagger-ui = []
 flake8 = [
    {file = "flake8-3.8.4-py2.py3-none-any.whl", hash = "sha256:749dbbd6bfd0cf1318af27bf97a14e28e5ff548ef8e5b1566ccfb25a11e7c839"},
    {file = "flake8-3.8.4.tar.gz", hash = "sha256:aadae8761ec651813c24be05c6f7b4680857ef6afaae4651a4eccaef97ce6c3b"},
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "dspace-statistics-api"
-version = "1.4.0-dev"
-description = "A simple REST API to expose Solr view and download statistics for items in a DSpace repository."
+version = "1.4.0"
+description = "A simple REST API to expose Solr view and download statistics for items, communities, and collections in a DSpace repository."
 authors = ["Alan Orth <aorth@mjanja.ch>"]
 license = "GPL-3.0-only"

@@ -11,7 +11,7 @@ gunicorn = "^20.0.4"
 falcon = "^2.0.0"
 psycopg2-binary = "^2.8.6"
 requests = "^2.24.0"
-falcon-swagger-ui = "^1.2.1"
+falcon-swagger-ui = {git = "https://github.com/alanorth/falcon-swagger-ui.git"}

 [tool.poetry.dev-dependencies]
 ipython = { version = "^7.18.1", python = "^3.7" }
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -11,7 +11,7 @@ colorama==0.4.4; python_version >= "3.7" and python_version < "4.0" and sys_plat
 dataclasses==0.6; python_version < "3.7"
 decorator==4.4.2; python_version >= "3.7" and python_version < "4.0"
 falcon==2.0.0
-falcon-swagger-ui==1.2.1
+-e git+https://github.com/alanorth/falcon-swagger-ui.git@a44244c85dceccfcd249b62fea4ee82a8221e3d2#egg=falcon-swagger-ui
 flake8==3.8.4
 gunicorn==20.0.4
 idna==2.10
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,7 @@
 certifi==2020.12.5
 chardet==4.0.0
 falcon==2.0.0
-falcon-swagger-ui==1.2.1
+-e git+https://github.com/alanorth/falcon-swagger-ui.git@a44244c85dceccfcd249b62fea4ee82a8221e3d2#egg=falcon-swagger-ui
 gunicorn==20.0.4
 idna==2.10
 jinja2==2.11.2
--- a/tests/test_api_collections.py
+++ b/tests/test_api_collections.py
@@ -371,3 +371,6 @@ def test_post_collections_invalid_page(client):
    response = client.simulate_post("/collections", json=request_body)

    assert response.status_code == 400
+
+
+# vim: set sw=4 ts=4 expandtab:
--- a/tests/test_api_communities.py
+++ b/tests/test_api_communities.py
@@ -371,3 +371,6 @@ def test_post_communities_invalid_page(client):
    response = client.simulate_post("/communities", json=request_body)

    assert response.status_code == 400
+
+
+# vim: set sw=4 ts=4 expandtab:
--- a/tests/test_api_docs.py
+++ b/tests/test_api_docs.py
@@ -43,3 +43,6 @@ def test_get_status(client):

    assert isinstance(response.content, bytes)
    assert response.status_code == 200
+
+
+# vim: set sw=4 ts=4 expandtab:
--- a/tests/test_api_items.py
+++ b/tests/test_api_items.py
@@ -371,3 +371,6 @@ def test_post_items_invalid_page(client):
    response = client.simulate_post("/items", json=request_body)

    assert response.status_code == 400
+
+
+# vim: set sw=4 ts=4 expandtab:
Author	SHA1	Message	Date
Alan Orth	33dc210452	dspace_statistics_api/docs/openapi.json: Minor edit Better to leave the version in there because Swagger Editor doesn't like it without. Also, change the example page parameter for POSTing to /items and /collections, as it doesn't make sense to start on a later page if we have less items than our limit.	2020-12-27 13:53:59 +02:00
Alan Orth	282d5f644a	Move unreleased change to v1.4.0	2020-12-27 12:52:24 +02:00
Alan Orth	05e0e8bdca	openapi.json: Set the API version from config We don't need to hard code this in the JSON anymore since we are reading and modifying it now for the server config anyways.	2020-12-27 12:48:13 +02:00
Alan Orth	2567bb8604	dspace_statistics_api/app.py: Format with black	2020-12-27 12:27:01 +02:00
Alan Orth	4af3c656a3	CHANGELOG.md: Add note about totalPages	2020-12-27 12:26:32 +02:00
Alan Orth	4f8cd1097b	Rework paging The "totalPages" value in our response is calculated incorrectly. Instead of casting to int and rounding, we should rather round up to the next integer with math.ceil. This is a more correct way to get the value. Also update the indexer to use the same logic, although there the values are printed with +1 so they are more readable.	2020-12-27 12:22:07 +02:00
Alan Orth	a02211fd60	Update requirements Some checks failed continuous-integration/drone/push Build is failing Details Generated with poetry export: $ poetry export --without-hashes -f requirements.txt > requirements.txt $ poetry export --without-hashes --dev -f requirements.txt > requirements-dev.txt The `--without-hashes` is required to work around an issue with gunicorn pulling in a dependency on setuptools that poetry ignores. See: https://github.com/python-poetry/poetry/issues/1584	2020-12-25 13:03:32 +02:00
Alan Orth	fc814593c7	Use my fork of falcon-swagger-ui It has a newer Swagger UI (v3.38.0).	2020-12-25 12:57:58 +02:00
Alan Orth	7de1084f60	Add whitespace before vim modeline All checks were successful continuous-integration/drone/push Build is passing Details black wants this...	2020-12-24 13:12:06 +02:00
Alan Orth	6b78e82fe9	Add vim modeline to all tests	2020-12-24 13:11:12 +02:00
Alan Orth	4004515967	pyproject.toml: Update description All checks were successful continuous-integration/drone/push Build is passing Details	2020-12-23 16:15:46 +02:00
Alan Orth	d1229c2387	Adjust docs at root Don't use a static HTML file anymore. Now I simply print an XHTML page from the Falcon resource. This way I can use variables to add in the API version as well as a link to the Swagger UI. The list of API calls is still present on the README.md, though in the long run I might move them to some dedicated documentation or a GitHub wiki.	2020-12-23 16:12:50 +02:00