diff --git a/Design.md b/Design.md index 10bdde2..343af40 100644 --- a/Design.md +++ b/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.", +} +```