Readthedocs.org: Hope that the response body format from public API will be consistent

[KengoTODA]

Thanks for hacking such a useful product! 👏

Especially the public API is awesome for who's motivated to automate workflow.
With help from your public API v3, I successfully replaced puppeteer that makes my bot really fat and unstable.

Here I have a request for future development (API v4?), I hope it helps your hack and your community.

---

Currently the PATCH API like version update responses 204 without any response body. This means that the format of the response body is not so consistent, and users need to judge before they handle the response body by .json() or a similar way.

For instance, I have code to handle response status and body for error handling, and if API responses a JSON instead of an empty response body, I can shorten the following part:

    .then((res) => {
      if (res.status != 204) {
        return Promise.all([res.status, res.json()])
      } else {
        // 204 responses empty text, so json() doesn't work
        return Promise.all([res.status, res.text()])
      }
    })

to simple and intuitive code like below:

    .then((res) => {
      return Promise.all([res.status, res.json()])
    })

Thanks again for your hacking!

[stsewd]

Looks like we only return data on PUT, but not on PATCH. I think we should return data on PATCH too.

[stsewd]

Actually, we use django rest framework, 204 means no content https://www.django-rest-framework.org/api-guide/status-codes/#successful-2xx

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5

So, the response body is correct. We can't change the status code or add a body in apiv3, that will break backwards compatibility.

[stsewd]

And by the way, we have https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html to build docs from a pull request.

[KengoTODA]

Yes I know you're building a cool and official solution (I checked the blog post before). Mine is a kind of playground, and hope that it'll be deprecated after the official solution becomes stable and public. :+1:

[stsewd]

Closing this as the API response is correct for a 204

[KengoTODA]

Closing this as the API response is correct for a 204

Can I ask what you mean? It just means wontfix, right?
I confirmed that the response body is still in the TEXT format.

Then I will open a new issue to change the HTTP response status to 200, since 204 is cachable but the API response isn't.

[stsewd]

Can I ask what you mean? It just means wontfix, right? I confirmed that the response body is still in the TEXT format.

204 code means you shouldn't expect a body on the response.

Your "hack" is the correct way to handle it

    .then((res) => {
      if (res.status != 204) {
        return Promise.all([res.status, res.json()])
      } else {
        // 204 responses empty text, so json() doesn't work
        return Promise.all([res.status, res.text()])
      }
    })