From 5d68167f76bb0b0eb653d864f9a9e27e6293fdc0 Mon Sep 17 00:00:00 2001
From: Markus Willman <mpewil@utu.fi>
Date: Sat, 10 Mar 2018 10:45:34 +0200
Subject: [PATCH] wrap up: harden requirements files - things are less likely
 to break when left unattended - update README.md

---
 Dockerfile                  |  8 ++--
 README.md                   | 96 ++++++++++++++++++++++++++++++++++---
 requirements.dev.txt        |  8 ++++
 requirements.txt            | 14 +++---
 system-requirements.dev.txt |  2 +
 system-requirements.txt     |  4 +-
 6 files changed, 113 insertions(+), 19 deletions(-)
 create mode 100644 requirements.dev.txt
 create mode 100644 system-requirements.dev.txt

diff --git a/Dockerfile b/Dockerfile
index e8bc6ec..c5f117f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,13 +4,13 @@ MAINTAINER Markus Willman
 
 SHELL ["/bin/bash", "-c"]
 
-# update the system, install python and create symlinks and directories
+# update the system, install python 2.7 and create symlinks and directories
 RUN apt-get update -qqy --fix-missing \
 	&& apt-get upgrade -qqy \
 	&& apt-get install -qqy --no-install-recommends \
 	build-essential \
-	python \
-	python-dev \
+	python2.7 \
+	python2.7-dev \
 	python-pip \
 	python-setuptools \
 	supervisor \
@@ -30,7 +30,7 @@ WORKDIR /opt/services/smartbusstop
 COPY . /opt/services/smartbusstop
 ADD http://data.foli.fi/gtfs/gtfs.zip /opt/services/smartbusstop/data/gtfs.zip
 
-# install python dependencies opencv-python needs libgtk2.0-dev installed in the system, if we want to install it here (virtualenv pip)
+# install python dependencies, note: opencv-python needs libgtk2.0-dev installed in the system, if we want to install it here
 RUN pip --no-cache-dir install -r /opt/services/smartbusstop/system-requirements.txt \
 	&& rm -f /opt/services/smartbusstop/system-requirements.txt \
 	&& virtualenv /opt/services/smartbusstop/.venv \
diff --git a/README.md b/README.md
index 781951e..6c11c86 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,7 @@ The deploy branch **can not** be pushed to directly using command line tools, as
 it is protected in such a way, so make a merge request and accept it, to trigger a
 deploy, using gitlab web interface.
 
-## About the Flask Application (WIP)
+## About the Flask Application
 
 It will respond to requests based on which templates exist in the templates
 directory, excluding any templates placed in the internal sub directory.
@@ -105,22 +105,106 @@ harder to access unintended content through it. The ref argument can contain any
 alphanumeric characters underscores or dashes after the word kiosk for logging
 purposes. The ref argument is also preserved for all internal ajax calls. 
 
-### Javascript json endpoints (tentative)
+The application uses a fairly strict Content-Security-Policy regardless of which
+mode it is accessed under.
 
-#### Stop Information
+## Localization
+
+Localization is done using `Flask-Babel` to create or update gettext message catalogs
+the scripts in the `scripts` directory can be used. They **must** be ran from the
+repository root.
+
+When using docker translations are automatically compiled at build time.
+
+### Javascript JSON endpoints
+
+Note the endpoints rely on the standardized GTFS data from the archive over the data
+from Föli JSON API's which is non-standard whenever possible. For example GTFS data
+is used for all schedule data, over the SIRI SM (Stop Monitoring) endpoint even, 
+because we have no control over how much or how little data said endpoint produces
+whereas we have full control over GTFS data.
+
+Likewise bridging the two data sources is not reliable or trivial, this only done
+for shape information currently and even then multiple shapes can be returned for
+one vehicle in theory (the theoretical worst case being it would return all shapes
+for the current day for every vehicle).
+
+#### Stop information
 
 ```
 URI: /api/v1/info/<stopId>
-Data Source: http://data.foli.fi/gtfs/gtfs.zip
+Data Source: GTFS stops.txt
 Returns: JSON object corresponding to the provided stop code ammended with the
 stop_url field.
 ```
 
-#### Data Files
+#### Arriving buses
+
+```
+URI: /api/v1/arrivals/<stopId>/[<routeType>/?limit=<n>]
+Data Source: GTFS trips.txt + routes.txt
+Returns: next N arriving trips on a specific stop. The routeType parameter
+controls how much information is returned about each trip (head/full/partial),
+partial limits the stop points to 10 closest and head does not include stop points
+at all.
+```
+
+#### Routes for specific stop
+
+```
+URI: /api/v1/routes/<stopId>[/<type>/]
+Data Source: GTFS routes.txt
+Returns: a list of routes that stop at a specifc stop (route contains 1 to N
+trips, this does not contain trip info). The type parameter controls whether
+this returns the full route info (equivalent to 'head' routeType in arrivals
+endpoint) or just a list of short names.
+```
+
+#### Stop schedule (trips)
+
+```
+URI: /api/v1/trips/<stopId>/[<routeType>/?offset=<n>&limit=<m>]
+Data Source: GTFS trips.txt + routes.txt
+Returns: schedule information for a specific stop. This endpoint is a
+superset of the arrivals endpoint that can be used to retrieve paginated
+schedule information for the day routeType parameter behaves identically.
+```
+
+#### Trip information
+
+```
+URI: /api/v1/trip/<tripSlug>/
+Data Source: GTFS trips.txt + routes.txt
+Returns: the full stop point listing of any trip for today, intended for use
+with the arrivals or trips endpoints above (with routeType 'head').
+```
+
+#### Real time location information
+
+```
+URI: URI: /api/v1/locator[/<stopId>/<type>]
+Data Source: Föli SIRI Vehicle Monitoring
+Returns: vehicles in transit related to specific stop. The type parameter can
+be either 'raw' (returns the unfiltered VM response), 'nearby' (returns all
+buses within 5 kilometers of the selected stop) or 'routed' (returns all buses
+that stop at the selected stop).
+```
+
+#### Track specific bus
+
+```
+URI: URI: /api/v1/locator/vehicle/[<busId>/<getShape>/]
+Data Source: Föli SIRI Vehicle Monitoring + GTFS shapes.txt
+Returns: single vehicle record by the vehicle id (here busId) in SIRI, if 
+getShape is non-zero also includes shape information for the current route
+(lineref) and block (key 'shapes' in response). May return more than one shape.
+```
+
+#### Data files
 
 ```
 URI: URI: /api/v1/data/[<stopId>/]<path>.json
 Data Source: data directory
 Returns: the corresponding data file, if stopCode is provided files specific to
-that GTFS stop_code will have priority.
+that GTFS stop_id will have priority.
 ```
diff --git a/requirements.dev.txt b/requirements.dev.txt
new file mode 100644
index 0000000..7cac4ed
--- /dev/null
+++ b/requirements.dev.txt
@@ -0,0 +1,8 @@
+Flask>=0.12.2
+Flask-Babel
+speaklater
+six
+pytz
+transitfeed
+python-dateutil
+requests
diff --git a/requirements.txt b/requirements.txt
index 7cac4ed..42d2d24 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,8 +1,8 @@
-Flask>=0.12.2
-Flask-Babel
-speaklater
-six
+Flask==0.12.2
+Flask-Babel==0.11.2
+speaklater==1.3
+six==1.11.0
 pytz
-transitfeed
-python-dateutil
-requests
+transitfeed==1.2.16
+python-dateutil==2.6.1
+requests==2.18.4
diff --git a/system-requirements.dev.txt b/system-requirements.dev.txt
new file mode 100644
index 0000000..6c1399c
--- /dev/null
+++ b/system-requirements.dev.txt
@@ -0,0 +1,2 @@
+uWSGI>=2.0.15
+virtualenv>=15.1.0
diff --git a/system-requirements.txt b/system-requirements.txt
index 6c1399c..743ccbd 100644
--- a/system-requirements.txt
+++ b/system-requirements.txt
@@ -1,2 +1,2 @@
-uWSGI>=2.0.15
-virtualenv>=15.1.0
+uWSGI==2.0.17
+virtualenv==15.1.0
-- 
GitLab