Improve OpenAPI spec + documentation for responses

[joshtemple]

Hey Looker!

I’m one of the maintainers of Spectacles, a popular open-source tool for testing LookML for SQL, content, and data test errors.

We’re major users of the Looker API and have been using it for a long time with hundreds of Looker customers.

We’d love to use the OpenAPI spec that the Looker SDKs are generated from to enforce better type safety in Spectacles. However, most of the API endpoint responses are generic and under-specified in the OpenAPI spec.

For example, here’s one we use all the time to get query results: https://developers.looker.com/api/explorer/3.1/methods/Query/query_task_results

If you look at the spec, under “responses”, all that’s specified is a JSON string, which doesn’t give us any information about what fields we can expect in the response.

"responses": {
    "200": {
      "description": "The query results.",
      "content": {
        "text": {
          "schema": {
            "type": "string"
          }
        },
        "application/json": {
          "schema": {
            "type": "string"
          }
        }
      }
    }
  }
}

In practice, this lack of clarity on response format has caused issues for our library because we have to handle a variety of different response formats that we’ve encountered over the years. It’s also difficult to develop without testing this endpoint live, because we can never remember which fields are returned.

We would love it if Looker could take the time to improve the spec for popular endpoints (we’re particularly interested in things like Get Query Multi Results, Content Validator, and Run LookML Tests).

Most APIs that I’ve worked with in the past document the responses as well as the request—it’s important that developers know what to expect from an endpoint.