Skip to content

Fail fast on a missing or misnamed OpenAPI path parameter - #31

Draft
jimador wants to merge 1 commit into
mainfrom
fix/openapi-path-param-fail-fast
Draft

Fail fast on a missing or misnamed OpenAPI path parameter#31
jimador wants to merge 1 commit into
mainfrom
fix/openapi-path-param-fail-fast

Conversation

@jimador

@jimador jimador commented Aug 14, 2026

Copy link
Copy Markdown

Problem

OpenApiOperationTool.resolvePath skips substitution silently when a path
parameter's value is null, leaving the literal placeholder in the built URI.
A learned streaming API's getShow operation (GET /shows/{id}) hit this in
a downstream consumer: called without id, the tool sent GET .../shows/{id}
to the remote as-is, which 404'd every time. Nothing in the response or the
logs pointed at the missing argument — it read as "the API has no data."

That request can never succeed. OpenAPI 3 requires in: path parameters to be
required: true, so a missing one isn't optional data, it's a call to the
wrong URL.

Fix

resolvePath throws as soon as a declared path parameter has no value, naming
the parameter, the operation, and the argument keys that were actually
supplied — enough for the caller (often an LLM re-driving the call) to correct
itself instead of retrying the same dead end.

Query and header parameters are untouched; this only tightens path parameters,
which the spec already marks required.

Tests

Three new cases in OpenApiOperationToolTest: missing id, misnamed key
(imdbId instead of id), and a correctly supplied call still building the
substituted URL unchanged. Red-first: the missing-id case was confirmed
sending the percent-encoded literal (%7Bid%7D) to the mock before the fix.
164 tests green in embabel-api-client.

`resolvePath` skipped substitution silently when a path parameter's value
was null, leaving the literal placeholder in the built URI. A learned
streaming API's `getShow` operation (`GET /shows/{id}`) hit this in
production: called without `id`, the tool sent `GET .../shows/{id}` to
the remote as-is, which 404'd every time. Nothing in the response or the
logs pointed at the missing argument -- it just looked like the API had
no data.

That request could never have succeeded. OpenAPI 3 requires `in: path`
parameters to be `required: true`, so a missing one isn't optional data,
it's a call to the wrong URL. `resolvePath` now throws as soon as a
declared path parameter has no value, naming the parameter, the
operation, and the argument keys that were actually supplied -- enough
for the caller (often an LLM re-driving the call) to correct itself
instead of retrying the same dead end.

Query and header parameters are untouched; this only tightens path
parameters, which the spec already marks required.

Three new tests in OpenApiOperationToolTest cover a missing `id`, a
misnamed key (`imdbId` instead of `id`), and confirm a correctly
supplied call still builds the substituted URL unchanged. 164 tests
green in embabel-api-client.

Signed-off-by: James Dunnam <7660553+jimador@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant