API: updates to endpoint for triggering a new build about readthedocs.org

[agjohnson]

Actually, this API does have what I need, but the docs are wrong:

{
    "build": "{BUILD}",
    "project": "{PROJECT}",
    "version": "{VERSION}"
}

Instead the output is a much more complex response, not just string responses:

{
  build: {
    _links: { ... },
    ...,
    urls: { ... },
  },
  project: { ... },
  version: { ... },
};

[humitos]

@agjohnson note that {BUILD} syntax means it's a build object. You can find the structure for this obejct on the "Build details" section of the documentation: https://docs.readthedocs.io/en/stable/api/v3.html#build-details

[agjohnson]

It's in string quotes though, so implies this is an id/pk instead of a full object. I was not expecting to get a full object response from this API after looking at our docs.

[humitos]

It's with quotes because it's a JSON and if you don't use quotes there, it breaks Sphinx 🤷🏼

[agjohnson]

But that seems to be because we're using {BUILD} as a placeholder notation. The docs don't mention what this notation is or what data structures these refer to.

If we follow the pattern from other responses and instead show the full response, that would be clearer. Even a truncated response on the nested objects would be clearer, if we're worried the full response is too long.

[agjohnson]

I separated out fixing our API docs to make them clear. I have never noticed that our APIv3 docs comment many nested objects using strings and this could definitely be much clearer.

• #11408

Changes to the API are in #11407