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?