encourage type/length stability in best practice vignette

[maxheld83]

I think it's important to push type and length stability in R, as discussed in design, and embodied in purrr and vctrs.

I'm no expert on (RESTful) API design but I understand that length-stability is also considered a best practice there, i.e. an API should return [] or null on empty fields.

This also has a bearing on API wrapper packages, especially when the underlying API itself isn't (loosely) length-stable (looking at you, crossref API). In this case, a "naive" wrapper that simply transforms the returned JSON to R may bring the length instability into R, especially when the returned JSON is rendered in a data frame.

I'd love to see this issue (very briefly) addressed in the best practices API vignette and I'd be happy to add some (very carefully worded) 2-3 paragraphs in a PR if there's some interest and if my view of this is correct/relevant.

My idea of a best practice for R API wrappers would be:

• check whether API in question is length and type-stable
• if it is not, warn users (in the docs, not warning()) about those (few?) functions which import this instability to R
• if a manageable list of known possible fields is available, write wrapper(s) which make the API type stable by returning NA/NULL as applicable.

Does that make sense / seem relevant to anyone?

[hadley]

httr has been superseded in favour of httr2, so is no longer under active development. If this problem is still important to you in httr2, I'd suggest filing an issue offer there 😄. Thanks for using httr!