I am writing an R package to expose/simplify a particular SOAP API. I am relying heavily on httr, and I need advice on how to design the user experience for authenticating and then executing subsequent calls to my other functions which actually make use of the API. Would it be better to allow httr to manage the authentication cookie automatically in the background (using the handle_pool), or would it be better to have the authenticate function return an httr handle that the user can then pass to my other functions, akin to creating a database or file connection?
It could be convenient to not have the user worry about passing around connection objects after the initial authentication call and just specifying the web url. On the other hand, the user might want to "clean up their session" by closing (deleting) a specific handle for a particular site. To put it another way, is httr's handle pool a simple matter of convenience for interactive use, or would it be ok to build a package that uses the handle_pool for a user's R session as a means to keep authentication in place throughout that session?