Public-Environmental-Data-Partners / Public-Environmental-Data-Partners/EJAM-API
Expose more ejamit() / ejam2report() parameters through the API endpoints
Nobody has claimed this yet.
- Dominant language
- Jupyter Notebook
- Stars
- 1
- Forks
- 1
- Avg merge
- 38m
- Merged PRs (30d)
- 1
Description
Prepared by Claude Code on behalf of @ejanalysis.
Idea
Each key endpoint should accept most or all of the appropriate parameters of the EJAM function it wraps, so API users get (nearly) the flexibility R users have — e.g. pass any relevant ejamit() analysis parameter to the report/data endpoints, and ejam2report() display parameters to the report endpoints.
This has been on the roadmap in the EJAM docs for a while — the "Future plans" article lists: "allowing the API to use most or all of the same parameters as the functions ejamit() and ejam2report(), providing more features and flexibility in customizing reports." This issue makes that trackable. Related: Public-Environmental-Data-Partners/EJAM-API#4 (create different endpoints) and Public-Environmental-Data-Partners/EJAM-API#12 (accept a zipped-shapefile URL — one specific new parameter).
Proposed approach (draft-first in EJAM, then upstream here)
- Inventory & whitelist: classify
formals(ejamit)andformals(ejam2report)into HTTP-safe scalars/vectors (e.g.radius_donut_lower_edge,subgroups_type,include_ejindexes,calculate_ratios,extra_demog,thresholds, theshow*toggles,analysis_title, …) vs not-exposable (functions/callbacks likeupdateProgress, shiny-session objects,in_shiny, quadtree objects). The whitelist becomes the endpoint contract, documented per-parameter in the plumber annotations so Swagger (/__docs__/) shows them. - Prototype on the EJAM package's
/draftrouter (added in Public-Environmental-Data-Partners/EJAM#499, which ships a verbatim mirror of this repo's code runnable locally viaEJAM:::ejamapi_local()):/draft/report2already exposes ~15ejamit()params and is the working prototype; extend it and/draft/ejamitto the full whitelist. - Tests: each whitelisted param at least round-trips without error, with spot-checks that a few visibly change output (
include_ejindexes,subgroups_type, thresholds). - Propose here once proven: the same expansion for production
GET/POST /reportandPOST /data, via the mirror-edit → EJAM-API PR workflow documented in EJAM'sinst/plumber/ejam-api/SYNC.md. Complex params may need to be POST-body only, to keep GET URLs within length limits.
Planning details live in EJAM's planning/plumber-sync-with-ejam-api-plan.md §8 (branch API-in-EJAM, PR Public-Environmental-Data-Partners/EJAM#499).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with planning/plumber-sync-with-ejam-api-plan.md §8 and the existing /draft/report2 and /draft/ejamit routes in the EJAM mirror. Inventory formals(ejamit) and formals(ejam2report), review the synchronization process in inst/plumber/ejam-api/SYNC.md, and run the draft route tests. Done means an agreed parameter whitelist, round-trip and output-change tests, and a documented proposal for the production endpoints.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- r
- Domain
- api, backend-api-design, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100