OpenEnergyPlatform / OpenEnergyPlatform/oeplatform

Name the endpoint groups, and say in the reference which one is superseded

Open
#2,459 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation OEKG-API
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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.