add suggestions for API packages (#496)

Co-authored-by: mark padgham <[email protected]>
Co-authored-by: Yanina Bellini Saibene <[email protected]>

booknews.Rmd

@@ -2,6 +2,10 @@
 
 ## dev (0.9.0)
 
+- 2023-09-15, add suggestions for API packages (#496).
+
+- Translation to Spanish!
+
 - 2023-07-17, Update Aims and Scope to include translation packages, remove experimental text-processing categories, and provide clarifications around API wrappers
 
 - 2023-05-04, Added link to Bioconductor book (#663, `@llrs`).

pkg_building.Rmd

@@ -62,6 +62,24 @@ If providing graphical user interface (GUI) (such as a Shiny app), to facilitate
 
 The [`tabulizer` package](https://github.com/ropensci/tabulizer) e.g. has an interactive workflow to extract tables, but can also only extract coordinates so one can re-run things as a script. Besides, two examples of shiny apps that do code generation are [https://gdancik.shinyapps.io/shinyGEO/](https://gdancik.shinyapps.io/shinyGEO/), and [https://github.com/wallaceEcoMod/wallace/](https://github.com/wallaceEcoMod/wallace/).
 
+### Input checking
+
+We recommend your package use a consistent method of your choice for [checking inputs](https://blog.r-hub.io/2022/03/10/input-checking/) -- either base R, an R package, or custom helpers.
+
+### Packages wrapping web resources (API clients)
+
+If your package accesses a web API or another web resource,
+
+- Make sure requests send an [user agent](https://httr2.r-lib.org/articles/wrapping-apis.html#user-agent), that is, a way to identify what (your package) or who sent the request. The users should be able to override the package's default user agent. Ideally the user agent should be different on continuous integration services, and in development (based on, for instance, the GitHub usernames of the developers).
+- You might choose different (better) defaults than the API, in which case you should document them.
+- Your package should help with pagination, by allowing the users to not worry about it at all since your package does all necessary requests.
+- Your package should help with rate limiting according to the API rules.
+- Your package should reproduce API errors, and possibly explain them in informative error messages.
+- Your package could export high-level functions and low-level functions, the latter allowing users to call API endpoints directly with more control (like `gh::gh()`).
+
+For more information refer to the blog post [Why You Should (or Shouldn't) Build an API Client](https://ropensci.org/blog/2022/06/16/publicize-api-client-yes-no).
+
+
 ## Code Style {#code-style}
 
 - For more information on how to style your code, name functions, and R scripts inside the `R/` folder, we recommend reading the [code chapter in The R Packages book](https://r-pkgs.org/Code.html). We recommend the [`styler` package](https://github.com/r-lib/styler) for automating part of the code styling. We suggest reading the [Tidyverse style guide](https://style.tidyverse.org/).

pkg_building.es.Rmd

@@ -68,6 +68,23 @@ Esto puede incluir la generación automática del código necesario para reprodu
 El paquete [`tabulizer`](https://github.com/ropensci/tabulizer) por ejemplo, tiene un flujo de trabajo interactivo para extraer tablas, pero también puede extraer sólo coordenadas, por lo que se pueden volver a ejecutar los mismos pasos como un script.
 Otros dos ejemplos de aplicaciones shiny que generan código son [https://gdancik.shinyapps.io/shinyGEO/](https://gdancik.shinyapps.io/shinyGEO/)y [https://github.com/wallaceEcoMod/wallace/](https://github.com/wallaceEcoMod/wallace/).
 
+### Comprobación de entradas
+
+Recomendamos que tu paquete utilice un método coherente de tu elección para [comprobar las entradas](https://blog.r-hub.io/2022/03/10/input-checking/) -- ya sea R base, un paquete de R o ayudantes personalizados.
+
+### Paquetes que envuelven recursos web (clientes API)
+
+Si tu paquete accede a una API web o a otro recurso web,
+
+- asegúrate de que las peticiones envían un [agente de usuario](https://httr2.r-lib.org/articles/wrapping-apis.html#user-agent) es decir, una forma de identificar qué (tu paquete) o quién envió la solicitud. Se debe poder anular el agente de usuario por defecto del paquete. Lo ideal sería que el agente de usuario fuera diferente en los servicios de integración continua y en los de desarrollo (basándose, por ejemplo, en los nombres de usuario de GitHub de quienes desarrollan).
+- Puede que elijas valores por defecto diferentes (mejores) que los de la API, en cuyo caso deberías documentarlos.
+- Tu paquete debería ayudar con la paginación, permitiendo que quienes lo usen no se preocupen en absoluto de ella, ya que tu paquete realiza todas las peticiones necesarias.
+- Tu paquete debe ayudar a limitar la tasa de acuerdo con las normas de la API.
+- Tu paquete debe reproducir los errores de la API, y posiblemente explicarlos en mensajes de error informativos.
+- Tu paquete podría exportar funciones de alto nivel y funciones de bajo nivel, estas últimas permitiendo a las personas que lo usen llamar directamente a los puntos finales de la API con más control (como `gh::gh()`).
+
+Para más información, consulta el artículo del blog [Por qué deberías (o no) crear un cliente API](https://ropensci.org/blog/2022/06/16/publicize-api-client-yes-no).
+
 ## Estilo del código {#code-style}
 
 - Para más información sobre cómo dar estilo a tu código, nombrar funciones y scripts de R dentro de la carpeta `R` te recomendamos que leas el [capítulo "Code" (Código) del libro R Packages](https://r-pkgs.org/Code.html).