[gaurav]

src/nodenorm/webapp/openapi.json was copied from NodeNorm Redis and never pruned, so it advertised TRAPI 1.5, carried 145 schemas that no path referenced, named RENCI's developer as the contact, pointed readers at /get_curie_prefixes (a 404 here) and failed openapi-spec-validator. This PR rewrites it from scratch against the six routes build_handlers() registers, and fixes the endpoints that didn't do what the document says: GET /get_allowed_conflations returned HTTP 500 on every deployment, /get_semantic_types lower-cased every Biolink class, /get_setid answered 500 instead of its error field, /status answered 500 rather than status: error when Elasticsearch was down, /get_normalized_nodes read conflate=0 as true, and a POST body that wasn't JSON answered 500 rather than 400. Closes #35. Closes #36. Closes #47.

A test module now holds the document to the code, and /openapi.json redirects to /webapp/openapi.json so the address NodeNorm Redis, SmartAPI and Babel Validation expect works here, which unblocks #34. Returning a list from POST /get_setid, as NodeNorm Redis does, is a breaking change left to #48, which builds on this one.

Calls worth overruling

• Two response shapes change. /get_allowed_conflations returns {"conflations": [...]} and /get_semantic_types returns biolink:NamedThing rather than biolink:namedthing, both to match NodeNorm Redis, which clients were written against.
• Boolean flags are strict. /get_normalized_nodes accepts the strings Pydantic accepted in NodeNorm Redis (true/false, 1/0, yes/no, on/off, t/f, y/n, any case) in the query and the POST body, and answers 400 for anything else, including an empty value. Before, anything but false meant true.
• POST /get_setid is documented as it answers today, an object keyed by input index ("0", "1", …); Return POST /get_setid results as a JSON list, as NodeNorm Redis does #48 changes both the code and the document.
• /status reports babel_version: null when the cluster can't be reached, rather than omitting the field.
• servers is a static list of the production, ci and test deployments at ITRB plus localhost (production first, as clients default to the first), not generated from environment variables as in NodeNorm Redis. Localhost stays as development so a local Swagger UI can reach itself; Don't list localhost as the development server in the registered OpenAPI document #54 asks whether the registered document should keep it.
• /version is documented rather than removed (Remove TRAPI-specific content and references to missing endpoints from the OpenAPI document #36 offered either). It reports the deployed commit, which /status doesn't.
• Error responses are the Tornado 400s the handlers raise, not the FastAPI 422/HTTPValidationError the old document copied.
• Contact is Will Liu and the team is DOGSURF, per Update the OpenAPI information #35, where Will confirmed both. The infores is infores:nodenorm, added for this service by Add infores:nodenorm for NodeNorm ElasticSearch and rename the Redis entry biolink/information-resource-registry#140, which renamed infores:sri-node-normalizer to NodeNorm Redis. The RENCI terms of service are unchanged for now (see below).

What's here

The document shrinks from about 3,000 lines to about 600: six paths, eight schemas, one shared example taken from the live CI instance. info.version is bumped to 1.1.0 because /status reports it and response shapes changed. handlers/curie_prefix.py, an unregistered copy of the semantic-types handler, is deleted. Both POST handlers parse their bodies with a shared load_json_body(), so a body that isn't JSON, or isn't UTF-8, gets a 400. Route patterns are matched exactly; a comment in build_handlers() says why.

tests/test_openapi.py validates the document, both the file and the copy served at /openapi.json, and checks its paths, methods (HEAD included), query parameters, POST body fields and SetIDResponse schema against the handlers. It also mounts each fixed handler with a fake or unreachable Elasticsearch client and validates the answers against the documented schemas, so none of it needs the su10 host. The README's "OpenAPI document" section says how the document is kept in sync.

What it deliberately does not do

• It doesn't generate the document from code, which Tornado can't do; the sync tests stand in. They don't yet check the /get_normalized_nodes, /version or /status-when-up responses against their schemas without the su10 host: Check /get_normalized_nodes, /version and /status responses against the OpenAPI schemas without an Elasticsearch host #51.
• docker/patches/health.py is a stale copy of the health handler; deleting it is Delete docker/patches/health.py, an unused stale copy of the health handler #45. Running the host-free tests in GitHub Actions is Run the tests that need no Elasticsearch host in GitHub Actions #44, and the requires-python range that stops uv run resolving the project is Raise requires-python to >=3.10 so uv run can resolve the project #43.
• Conformance tests against each deployment are in Check each NodeNorm deployment's response shapes against its OpenAPI document TranslatorSRI/babel-validation#153.

Verification

On 3d000cc, openapi-spec-validator passes, and the whole suite passes except the four integration tests that need the su10 host (test_node_normalization_get/_post, and test_get_endpoint/test_post_endpoint for set IDs).

After merging

Nothing blocks merging. Registering at SmartAPI (#34) waits until this is deployed to production: SmartAPI's uptime check tests only the first server, whose /get_allowed_conflations 500s until then. Deferred:

• Replace the RENCI terms of service; the software belongs to the BioThings group at Scripps, the data is RENCI's Babel output.
• Decide whether NodeNorm ES needs its own copy of the endpoint semantics that info.description links to in NodeNorm Redis's documentation/API.md, in case NodeNorm Redis changes.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Request schemas conflict with runtime behavior, malformed UTF-8 can still produce HTTP 500, and the contact remains unresolved.

2 open findings

• Catch UnicodeDecodeError for malformed UTF-8 bodies · New
• Update document contact fields to Everaldo · New

What changed in this PR

Rewrites the OpenAPI specification to reflect the Elasticsearch-backed service and aligns endpoint behavior with the documented contract.

Changes:

• Replaces obsolete TRAPI documentation with six current routes and schemas.
• Fixes route matching, status handling, boolean parsing, conflations, semantic types, and set-ID errors.
• Adds contract and regression tests.

File	Description
README.md	Documents OpenAPI maintenance.
docker/​configuration/​config.json	Excludes OpenAPI redirect from telemetry.
pyproject.toml	Adds schema-validation test dependencies.
src/​nodenorm/​config/​config.default.json	Updates telemetry exclusions.
src/​nodenorm/​handlers/​__init__.py	Fixes routes and adds redirect.
src/​nodenorm/​handlers/​conflations.py	Returns a documented object response.
src/​nodenorm/​handlers/​curie_prefix.py	Removes an unused handler.
src/​nodenorm/​handlers/​health.py	Handles unavailable Elasticsearch.
src/​nodenorm/​handlers/​normalized_nodes.py	Adds strict boolean parsing.
src/​nodenorm/​handlers/​semantic_types.py	Preserves Biolink class casing.
src/​nodenorm/​handlers/​set_identifiers.py	Validates bodies and serializes errors.
src/​nodenorm/​webapp/​openapi.json	Rewrites the API specification.
tests/​test_openapi.py	Adds contract and regression coverage.
tests/​test_set_identifiers.py	Updates POST request and response expectations.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[shuchenliu]

consolidated changes and merged with #58