I'm working on an OpenAPI 3 spec for an older-style XML API that has one endpoint for all queries. It always returns the same data structure, but depending on the request's query parameters, different response fields will be populated. In fact, the prose API spec suggests using HTTPS only for login, and HTTP for everything else. (Don't shoot the messenger, I don't own the API, I'm just a client.)
I'd like to separate those semantically-different requests in the spec, something like:
paths:
/:
get:
operationId: login
parameters:
- name: username
- name: password
get:
operationId: getCallsign
parameters:
- name: s
description: session token
- name: callsign
description: perform a callsign info lookup
get:
operationId: getDxcc
parameters:
- name: s
description: session token
- name: dxcc
description: perform a DXCC info lookup
However, it doesn't seem like this is supported. The combination of path and method must be unique, so GET /
must be a single operation.
paths:
/:
get:
operationId: doEverything
parameters:
- name: username
- name: password
- name: s
description: session token
- name: callsign
description: perform a callsign info lookup
- name: dxcc
description: perform a DXCC info lookup
Is there any way to separate those distinct operations on one endpoint? If not, I can write a thin client library over the generated one which makes the use of the API more clear, but it'd be nice to tease apart the subtleties directly in the spec.