Lots of API related information for the applications. No internet access so cannot review weather services yet.

Design.md

@@ -212,6 +212,7 @@ objects, constraints, schedules, etc being added in the revision. Example:
     ```
 - Scripts shall have a consistent style and formatting. Developer may use the
 style of their choice.
+- Scripts shall assume a Docker environment using image `debian:trixie-slim`.
 
 ### Tables
 
@@ -340,8 +341,145 @@ For each `ZIP_CODE`, calculate the following:
 
 ## 4. Response API
 
+Developer: TBD
+
+Language: Developer's choice.
+Node.js using Express recommended unless a better use case can be made.
+
 ### Description
 
+Listener API which receives requests from the front end and queries the database on their behalf. This program is responsible for adding new `ZIP_CODE`'s to the database and requesting that the weatherman load the data for these when that is done.
+
 ### Requirements
 
--
+- Program shall listen JSON #1 in the appendix as its initiating request.
+- Program shall provide JSON #2 as a response to the request.
+- Program shall access the database in section #2 as user `geo`.
+- Program shall acquire the weather data from the `loc_weather_agg` table..
+- Program shall post any new zip codes in the `loc` table.
+- program shall update `loc.last_accessed_date` for the zip codes it retrieved data for.
+
+# Appendix - JSON Requests and Responses
+
+## 1. Request: Front End to Response API
+
+- Data shall be de-duplicated so that any one zip only appears once.
+- All payloads shall contain the version number so that the server knows which
+response to provide, in case the format changes in the future.
+- Commas are acceptable after every data element, even ending ones.
+
+```json
+{
+    "version": "1.0",
+    "data": [
+        "zip_code": "85901",
+        "zip_code": "86004",
+        "zip_code": "86001",
+    ],
+}
+```
+
+## 2. Response: Response API to Front End
+
+- Version shall be included so that the front end knows how to parse the response.
+- Commas are acceptable after every element, including the ends of lists.
+- Zip codes and dates shall be treated as strings.
+- Temperature data shall be treated like numbers.
+
+```json
+{
+    "version": "1.0",
+    "data": [
+        {
+            "zip_code": "85901",
+            "last_update_date": "1900-01-01T15:00:00+0000",
+            "mean_high": 64.237,
+            "mean_low": 38.758,
+            "median_high": 65,
+            "median_low": 43,
+            "mode_high": 68,
+            "mode_low": 47,
+            "today_high": 58,
+            "today_low": 33,
+            "tomorrow_high": 61,
+            "tomorrow_low": 37,
+        },
+        {
+            "zip_code": "86004",
+            "last_update_date": "1900-01-01T15:00:00+0000",
+            "mean_high": 45.46,
+            "mean_low": 22.235,
+            "median_high": 45,
+            "median_low": 19,
+            "mode_high": 42,
+            "mode_low": 22,
+            "today_high": 46,
+            "today_low": 25,
+            "tomorrow_high": 52,
+            "tomorrow_low": 12,
+        },
+        {
+            "zip_code": "86001",
+            "last_update_date": "1900-01-01T15:00:00+0000",
+            "mean_high": 45.64,
+            "mean_low": 22.532,
+            "median_high": 44,
+            "median_low": 18,
+            "mode_high": 41,
+            "mode_low": 21,
+            "today_high": 45,
+            "today_low": 24,
+            "tomorrow_high": 51,
+            "tomorrow_low": 11,
+        },
+    ],
+}
+
+```
+
+## 3. Request: Applications to Weather Provider (TBD)
+
+(TBD: How to parse a request to the weather service.)
+
+## 4. Response: Weather Provider (TBD) to Applications
+
+(TBD: How to read a response from the weather service.)
+
+## 5. Request: New ZIP_CODE Needs Processed
+
+Notification from the `reporter` for the `weatherman` to kick off an ad hoc run.
+
+This data never leaves the server and cannot come from outside sources, the endpoint will not available to the public, it is accessed via localhost.
+
+Zip codes do not need provided since the `reporter` has already inserted and committed them to `loc`.
+
+```json
+{
+    "data": "run",
+}
+```
+
+## 6. Response: ZIP_CODE Data Now Available
+
+Response from `weatherman` program to `reporter`.
+
+If the `reporter` sees this, then it continues with building a response for the front end.
+
+```json
+{
+    "data": "ready",
+}
+```
+
+## 7. Response: Issue Loading New ZIP_CODE's
+
+Response from `weatherman` program to `reporter`.
+
+If the `reporter` happens to see this, it provides
+
+```json
+{
+    "data": "error",
+    "error": "Message about what went wrong, which may get forwarded to the user.",
+}
+```