OpenEnergyPlatform / OpenEnergyPlatform/oeplatform
Name the endpoint groups, and say in the reference which one is superseded
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 65
- Forks
- 29
- Avg merge
- 15h 25m
- Merged PRs (30d)
- 32
Description
Parent
Spec: #2454 — Document and teach the OEKG REST API. Derived from WF-14 decision D7.
What to build
The reference's accordions are named and ordered deliberately instead of derived from URL paths, so that a prose page can link to a stable anchor and a reader can tell the two scenario-bundle groups apart.
Measured: only 33 tag declarations exist across the whole API, all on advanced and schema-meta endpoints — nothing on datasets, nothing on OEKG, so every OEKG path takes a lowercase path-derived tag. And the pair that looks like one domain accidentally split in half is not one domain: one is the single legacy RPC route, the other is the entire new REST API. They render as adjacent accordions one letter apart with nothing saying which supersedes which.
The fix says "superseded" inside the reference, where it is covered by the drift guard, rather than only in prose that nothing checks.
Acceptance criteria
- Every scenario-bundle endpoint declares an explicit tag rather than inheriting a path-derived one.
- The generator settings carry an ordered tag list, each entry with a one-line description.
- The legacy RPC group's description states that it is superseded and names its replacement.
- The tags and their descriptions appear in the committed artifact, and are therefore covered by the drift guard from the reference ticket.
- The anchors are stable enough for prose pages to link into them by tag.
- Changelog entry.
Blocked by
- #2457 — the generated API reference — the artifact and its guard must exist before the tag curation can be covered by them.
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 the generated API reference and its drift guard from #2457, then locate the generator settings and scenario-bundle endpoint tag declarations. Add the ordered tags, descriptions, supersession note, committed artifact updates, and changelog entry; done means the stable anchors and all acceptance criteria are represented in the reference.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100