Creating an R package for a REST API: From scratch or OpenAPI specification

Package development
1

Hi,

I am looking for any thoughts or advice around building an R package that wraps a REST API. In particular, if the API provides an OpenAPI specification, then you can use that and a command-line tool (GitHub - OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)) to automatically create a comprehensive and fully documented R package.

I have tried this with the OpenAPI specification for the API I want to create the package for...and the R package looks fine. It looks very complete but maybe clunky. And I worry about long-term maintenance for a package generated auto-magically. This approach has advantages of being low effort, but I am unsure if the package will have an R API that is enjoyable and user-friendly.

However, the alternative is to write an R package "from scratch" where you have complete control over the R API and can make more opinionated design decisions to make the package user friendly. The REST API I am interested in has about 100+ endpoints, so the manual approach is non-trivial.

Does anyone have experience using the OpenAPI generator to create APIs for other languages (e.g., R)? Does anyone have strong feelings about the generator versus manual approach for creating an R package for a REST API?

I am just looking for any thoughts/comments in this area. I know lots of members of the R community create R packages to wrap REST APIs and so I am hoping someone has weighed the pros and cons of these approaches and can offer wisdom.

Thanks for your time.

2

Hi @mattwarkentin,

I’ve used this approach across different languages, including R, and found that a hybrid strategy works best:

  • Start with the generator: Use it to create the initial client and leverage the auto-generated docstrings/Roxygen documentation. This gives you a solid foundation and a good estimate of the codebase size you’ll need to maintain.
  • Customize the package: I then build the package according to my own design rather than the generator’s architecture. Over time, I selectively migrate useful parts and discard implementations or design decisions I don’t agree with.
  • For example, the generator might use httr or httr2 depending on your Documentation for the r Generator | OpenAPI Generator. Personally, I prefer CRAN: Package curl to keep the package lightweight and avoid dependency management headaches. This means I sometimes need to reimplement features that those libraries already solve, but it gives me more control.
  • Trade-offs: Ultimately, it comes down to how much time you’re willing to invest in maintaining your own implementation versus relying on external packages.

Take Java for example, the situation is more complex because multiple client types are supported. The difficulty largely depends on which Java version you target and which HTTP client and JSON parsing libraries you choose. These decisions can significantly impact compatibility, performance, and maintainability.

3

Thanks for taking the time to write this response, @vedoa. I appreciate it. And I think you provide a sensible approach that balances leveraging some of the benefits of the auto-generated code from the OpenAPI generator and then customizing the package with your own design considerations. Thanks again!

1 Like