Add feedback and contribution endpoints to OpenAPI spec#74
Conversation
|
It isn't entirely clear what the product vision is for this yet. Doubling down on Dynamo might not be the best option here, given that we don't know the downstream queries yet. That said, the deadline seems to be the driving factor here so configuring RDS and designing a long term solution doesn't seem key at this moment. General feedback based on the proposal:
Also, an audit should be done on if this openapi schema is current. We were moving away from this file and instead using the FastAPI automatic Swagger docs. In that workflow we would start defining the Pydantic schema contracts first versus this file. |
|
Re; DynamoDB: agreed, this choice is deadline-driven. The query patterns for now are simple (write feedback, read summary by tile_id), so DynamoDB handles it fine. Re; httpx: noted, will use aiohttp instead. Re; SNS/SES: good call. If SES setup is heavy, we could start with just writing to DynamoDB and log the email payloads, then wire up the actual email delivery once SES is configured. Re; the OpenAPI file: that's good context, I wasn't aware the team was moving toward Pydantic-first. If the preference is to define the Pydantic schemas and let FastAPI generate the docs, this YAML can serve as the design reference for what those schemas should look like rather than the source of truth |
|
SES is pretty quick, it is just something that would be required. No other comments from me at this point. :) |
| session_id: | ||
| type: string | ||
| format: uuid |
There was a problem hiding this comment.
Where does this session_id come from?
| map_center_lat: | ||
| type: number | ||
| minimum: -90 | ||
| maximum: 90 | ||
| map_center_lng: | ||
| type: number | ||
| minimum: -180 | ||
| maximum: 180 |
There was a problem hiding this comment.
Shouldn't this be a bbox instead of tile ID, zoom and lat long? Would be easier to use in analytics, I'd say. Keeping the zoom level might make sense.
| tile_id: | ||
| type: string | ||
| minLength: 1 | ||
| maxLength: 100 |
There was a problem hiding this comment.
I thought we were gonna take feedback via bbox, not tile ID?
| captcha_token: | ||
| type: string | ||
| minLength: 1 |
There was a problem hiding this comment.
Isn't there something better than these annoying CAPTCHAs?
Also, the details of the CAPTCHA service is unspecified, so we can't implement it in the client yet.
| rating: | ||
| type: integer | ||
| enum: [1, 2, 3] | ||
| description: "1: Not Great, 2: Ok, 3: Great!" |
There was a problem hiding this comment.
Ok is still not a good label.
There was a problem hiding this comment.
Agreed. Was hoping to get feedback from the research team on what they wanted there but have heard nothing back. I will prompt again, but did not want to hold implementation for that decision.
| tile_id: | ||
| type: string | ||
| minLength: 1 | ||
| maxLength: 100 |
There was a problem hiding this comment.
UTM Tiles are much shorter than 100 chars.
| enum: | ||
| - annotator | ||
| - share_data | ||
| - provide_models | ||
| - contribute_code |
There was a problem hiding this comment.
What do these values describe?
There was a problem hiding this comment.
These will be the checkbox fields from the contribute form.
| resource_link: | ||
| type: string | ||
| maxLength: 1000 |
There was a problem hiding this comment.
Should a link be of format uri / url ?
| tile_id: | ||
| type: string |
There was a problem hiding this comment.
Didn't we decide to to it per bbox instead of tile?
| $ref: '#/components/responses/5XX' | ||
|
|
||
| # =========================================================================== | ||
| # Feedback & Contribution Endpoints (unauthenticated — no bearer token) |
There was a problem hiding this comment.
All endpoints use Bearer token, I think we should continue this for now to be able to easily enable authentication if required.
|
Generally, all the technical details that are in the PR comments should be in the OpenAPI file inetad. No one will check the PR comments when we start the client/server implementation, but the source of truth will be the the OpenAPI document. |
3 participants
Add Feedback & Contribution API Endpoints
Add four new unauthenticated endpoints under /feedback/ to specification/openapi.yaml to support user feedback and community contribution forms for the global field boundaries release.
All existing endpoints, schemas, and security are unchanged. The new endpoints are appended after the existing paths and schemas.
Paths added:POST - /feedback/tile-rating
POST - /feedback/tell-us-more
POST - /feedback/contribute
GET - /feedback/tile-summary/{tile_id}
Authentication
These endpoints are unauthenticated. No bearer token required. Spam prevention is handled via browser-generated session_id, captcha (Cloudflare Turnstile) on the detailed forms, and IP rate limiting.
Schemas: TileRatingRequest, TileRatingResponse, TellUsMoreRequest, TellUsMoreResponse, ContributeRequest, ContributeResponse, TileSummaryResponse
Forms
Tile Rating: Quick 1-3 rating on a map tile (to be defined by current view area). No captcha. Dedup via upsert on tile_id + session_id.
Tell Us More: Detailed feedback (quality assessment, use case, optional contact info). Requires captcha. Triggers email notification.
Contribute: Community contribution interest (annotator, share data, provide models, contribute code). Requires captcha. Triggers email notification.
Implementation requirements
Storage: Three new DynamoDB tables (ftw_tile_ratings, ftw_detailed_feedback, ftw_contributions)
Email: AWS SNS topic for notifications on "Tell Us More" and "Contribute" submissions
Captcha: Cloudflare Turnstile server-side verification
Rate limiting: slowapi — 30 per min for tile rating, 5 per min for detailed forms, 60 per min for tile summary
Dependencies: boto3, httpx, slowapi, pydantic[email]
Open items
tile_id format TBD — accepted as opaque string (max 100 chars)
Turnstile site key + secret key: pending setup
SNS topic ARN: needs creation in AWS
Notification recipient email: TBD