Public-Environmental-Data-Partners / Public-Environmental-Data-Partners/EJAM-API

Expose more ejamit() / ejam2report() parameters through the API endpoints

Open
#52 1 comment 0 reactions 0 assignees View on GitHub

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)

  1. Inventory & whitelist: classify formals(ejamit) and formals(ejam2report) into HTTP-safe scalars/vectors (e.g. radius_donut_lower_edge, subgroups_type, include_ejindexes, calculate_ratios, extra_demog, thresholds, the show* toggles, analysis_title, …) vs not-exposable (functions/callbacks like updateProgress, 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.
  2. Prototype on the EJAM package's /draft router (added in Public-Environmental-Data-Partners/EJAM#499, which ships a verbatim mirror of this repo's code runnable locally via EJAM:::ejamapi_local()): /draft/report2 already exposes ~15 ejamit() params and is the working prototype; extend it and /draft/ejamit to the full whitelist.
  3. Tests: each whitelisted param at least round-trips without error, with spot-checks that a few visibly change output (include_ejindexes, subgroups_type, thresholds).
  4. Propose here once proven: the same expansion for production GET/POST /report and POST /data, via the mirror-edit → EJAM-API PR workflow documented in EJAM's inst/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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.