CHANGELOG.md: Add changes for v0.6.1

I had imagined plugging in an interactive Swagger or OpenAPI instance
here, but that's actually much more involved in Falcon than I want to
deal with right now.

CHANGELOG.md

@@ -4,6 +4,14 @@ 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).
 
+### [0.6.1] - 2018-10-31
+## Added
+- API documentation at root path (/)
+
+### [0.6.0] - 2018-10-31
+## Changed
+- Refactor project structure (note breaking changes to API and indexing invocation, see contrib and README.md)
+
 ### [0.5.2] - 2018-10-28
 ## Changed
 - Update library versions in requirements.txt

README.md

@@ -1,5 +1,7 @@
-# DSpace Statistics API [![Build Status](https://travis-ci.org/alanorth/dspace-statistics-api.svg?branch=master)](https://travis-ci.org/alanorth/dspace-statistics-api)
-A simple REST API to expose Solr view and download statistics for items in a DSpace repository. This project contains a standalone indexing component and a WSGI application.
+# DSpace Statistics API [![Build Status](https://travis-ci.org/ilri/dspace-statistics-api.svg?branch=master)](https://travis-ci.org/ilri/dspace-statistics-api)
+DSpace versions 4.0 and up include a [REST API](https://wiki.duraspace.org/display/DSDOC5x/REST+API) that allows the repository to be queried programmatically. The API exposes information about communities, collections, items, and bitstreams, but not item views or downloads. This project contains a lightweight indexer and a web application to make the view and download statistics available via a simple REST API that can be deployed simultaneously with DSpace's own.
+
+You can read more about the Solr queries used to gather the item view and download statistics on the [DSpace wiki](https://wiki.duraspace.org/display/DSPACE/Solr).
 
 ## Requirements
 
@@ -24,11 +26,11 @@ Set up the environment variables for Solr and PostgreSQL:
 
 Index the Solr statistics core to populate the PostgreSQL database:
 
-    $ ./indexer.py
+    $ python -m dspace_statistics_api.indexer
 
 Run the REST API:
 
-    $ gunicorn app:api
+    $ gunicorn dspace_statistics_api.app
 
 Test to see if there are any statistics:
 
@@ -59,14 +61,16 @@ This would expose the API at `/rest/statistics`.
 ## Using the API
 The API exposes the following endpoints:
 
-  - GET `/items` — return views and downloads for all items that Solr knows about¹. Accepts `limit` and `page` query parameters for pagination of results.
-  - GET `/item/id` — return views and downloads for a single item (*id* must be a positive integer). Returns HTTP 404 if an item id is not found.
+  - GET `/` — return a basic API documentation page.
+  - GET `/items` — return views and downloads for all items that Solr knows about¹. Accepts `limit` and `page` query parameters for pagination of results (`limit` must be an integer between 1 and 100, and `page` must be an integer greater than or equal to 0).
+  - GET `/item/id` — return views and downloads for a single item (`id` must be a positive integer). Returns HTTP 404 if an item id is not found.
 
-¹ We are querying the Solr statistics core, which technically only knows about items that have either views or downloads.
+The item id is the *internal* id for an item. You can get these from the standard DSpace REST API.
+
+¹ We are querying the Solr statistics core, which technically only knows about items that have either views or downloads. If an item 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.
 
 ## Todo
 
-- Add API documentation
 - Close DB connection when gunicorn shuts down gracefully
 - Better logging
 - Tests

contrib/dspace-statistics-api.service

@@ -12,7 +12,7 @@ Group=nogroup
 WorkingDirectory=/var/lib/dspace-statistics-api
 ExecStart=/var/lib/dspace-statistics-api/venv/bin/gunicorn \
           --bind 127.0.0.1:5000                             \
-          app:api
+          dspace_statistics_api.app
 ExecReload=/bin/kill -s HUP $MAINPID
 ExecStop=/bin/kill -s TERM $MAINPID
 

contrib/dspace-statistics-indexer.service

@@ -11,7 +11,7 @@ Environment=DATABASE_HOST=localhost
 User=nobody
 Group=nogroup
 WorkingDirectory=/var/lib/dspace-statistics-api
-ExecStart=/var/lib/dspace-statistics-api/venv/bin/python indexer.py
+ExecStart=/var/lib/dspace-statistics-api/venv/bin/python -m dspace_statistics_api.indexer
 
 [Install]
 WantedBy=multi-user.target

dspace_statistics_api/app.py

@@ -1,9 +1,16 @@
-from database import database_connection
+from .database import database_connection
 import falcon
 
 db = database_connection()
 db.set_session(readonly=True)
 
+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()
+
 class AllItemsResource:
     def on_get(self, req, resp):
         """Handles GET requests"""
@@ -63,10 +70,8 @@ class ItemResource:
 
         cursor.close()
 
-def on_exit(api):
-    print("Shutting down DB")
-
-api = falcon.API()
+api = application = falcon.API()
+api.add_route('/', RootResource())
 api.add_route('/items', AllItemsResource())
 api.add_route('/item/{item_id:int}', ItemResource())
 

dspace_statistics_api/database.py

@@ -1,7 +1,7 @@
-from config import DATABASE_NAME
-from config import DATABASE_USER
-from config import DATABASE_PASS
-from config import DATABASE_HOST
+from .config import DATABASE_NAME
+from .config import DATABASE_USER
+from .config import DATABASE_PASS
+from .config import DATABASE_HOST
 import psycopg2, psycopg2.extras
 
 def database_connection():

dspace_statistics_api/docs/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en-US">
+    <head>
+        <meta charset="UTF-8">
+        <title>DSpace Statistics API</title>
+    </head>
+    <body>
+        <h1>DSpace Statistics API</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>GET <code>/item/id</code> — return views and downloads for a single item (<code>id</code> must be a positive integer). Returns HTTP 404 if an item id is not found.</li>
+        </ul>
+
+        <p>The item id is the <em>internal</em> id for an item. You can get these from the standard DSpace REST API.</p>
+
+        <p>¹ We are querying the Solr statistics core, which technically only knows about items that have either views or downloads. If an item 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.</code>
+    </body>
+</html>

dspace_statistics_api/indexer.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python
 #
 # indexer.py
 #
@@ -30,10 +29,10 @@
 # See: https://solrclient.readthedocs.io/en/latest/SolrClient.html
 # See: https://wiki.duraspace.org/display/DSPACE/Solr
 
-from database import database_connection
+from .database import database_connection
 import json
 import psycopg2.extras
-from solr import solr_connection
+from .solr import solr_connection
 
 def index_views():
     # get total number of distinct facets for items with a minimum of 1 view,

dspace_statistics_api/solr.py

@@ -1,4 +1,4 @@
-from config import SOLR_SERVER
+from .config import SOLR_SERVER
 from SolrClient import SolrClient
 
 def solr_connection():