1

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.

Chris Keller
  • 374
  • 2
  • 12

1 Answers1

1

As Helen points out, this answer addresses the question: operations in Swagger/OpenAPI are keyed by the HTTP verb and the path, so a single endpoint that does multiple distinct things can't be broken up. It has to be a single mega-operation.

Chris Keller
  • 374
  • 2
  • 12