phase 4 first review and QA

2026-08-17 17:32:24 +01:00
parent 1a6840d16c
commit b072e2c3dc
3 changed files with 145 additions and 16 deletions
@@ -1,4 +1,3 @@
-
 # API Documentation

 This document describes the PX-Web API used by hagfish to fetch Faroese fisheries statistics from the official Statbank.
@@ -7,6 +6,62 @@ This document describes the PX-Web API used by hagfish to fetch Faroese fisherie
 - **GET**: Returns metadata (table structure, dimension codes, labels)
 - **POST**: Returns data in JSON-stat2 format

+## Endpoint Reference
+
+### Health Check
+- **GET** `/healthz` - Returns 200 OK if service is running
+
+### Species Lookup
+- **GET** `/api/species` - Returns list of all species codes and Faroese names
+
+### Zones Lookup  
+- **GET** `/api/zones` - Returns list of all economic zone codes and labels
+
+### Gear Lookup
+- **GET** `/api/gear` - Returns list of all fishing gear codes and labels
+
+### Landings Data
+- **GET** `/api/landings` - Returns filtered landing records
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `month` | string | No | Single month filter (legacy, e.g., `2024M01`) |
+| `month_from` | string | No | Start of date range (inclusive, e.g., `2024M01`) |
+| `month_to` | string | No | End of date range (inclusive, e.g., `2024M12`) |
+| `species` | string | No | Filter by species code (e.g., `COD`) |
+| `gear` | string | No | Filter by gear code (e.g., `TR1`) |
+| `zone` | string | No | Filter by zone code (e.g., `FO`) |
+| `measure` | string | No | Filter by measure type (`MASS` or `VALUE`) |
+| `limit` | integer | No | Max results (default: 10000, max: 10000) |
+
+**Example:**
+
+bash curl "http://localhost:8090/api/landings?month_from=2024M01&month_to=2024M06&species=COD&limit=1000"
+
+
+### Summary Aggregates
+- **GET** `/api/summary` - Returns aggregated statistics
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `species` | string | No | Filter aggregations by species code |
+
+**Response Fields:**
+- `monthly`: Array of `{month, total_mass, total_value}`
+- `top_species`: Array of top 10 species by value
+- `price_trend`: Array of `{month, price_per_kg}`
+
+### Parquet Export
+- **GET** `/api/export.parquet` - Downloads full dataset as Parquet file
+
+**Note:** Triggers temp file creation in system temp directory with automatic cleanup after 300 seconds.
+
+---
+
 ## Metadata Request (GET)

 ### Requestbash
@@ -183,10 +238,12 @@ indices
 - [ ] Parquet export tested
 - [ ] Error handling for network timeouts implemented

---
+Summary of Changes
+File	Change	Reason
+src/api.rs	Added MAX_LIMIT constant and hard cap	Prevent unlimited query results
+src/api.rs	Replaced CorsLayer::permissive() with explicit origins	Security hardening
+src/api.rs	Updated tempfile::Builder with prefix	Ensure cleanup function finds files
+src/api.rs	Added test_get_landings_range_filter test	Cover new range-filtering logic
+src/types.rs	Added allowed_origins field to Config	Support CORS configuration
+docs/API.md	Added endpoint reference table	Document new parameters

-## References
-
- Official PxWeb documentation: https://pxweb.github.io/docs/
- JSON-stat2 specification: http://json-stat.org/format/
- Hagstova Føroya: https://www.hagstova.fo/