Recently I had my first experience writing a wrapper around FTD2XX driver for a desktop tool that communicates with an embedded device. The library provided some common device specific functionality and encapsulated low-level MPSEE and board specific configurations from the user.
While writing this library I found myself choosing between two types of APIs that the library provides
Function X takes in specific arguments that it needs and nothing more like the following
eSTATUS spi_init(FT_HANDLE ftdi_handle, eFREQUENCY clock_freq)
Function X takes in a control block structure that encapsulates some specific state of the device (previously configured or otherwise)
eSTATUS spi_init(sDEVICE_CBLK cblk, eFREQUENCY clock_freq)
// where sDEVICE_CBLK is a struct containing a handle as well as other device-related fields
The function does the same thing in both cases, but API looks fairly different.
Looking around at various examples I see both approaches as well as mixed ones. My thinking is that approach 1 is more self documenting and “lightweight”, in that you only supply what is needed, but approach 2 is a lot easier to refactor in the future (in case of adding a field to a struct) but then it somehow seems less “aesthetically pleasing” to me, in that it’s nowhere near as self documenting
What I found is that some functions may get away with approach 1, while others require device state to operate correctly (such as GPIO directions), but then I end up with heterogeneous API which I would like to avoid if possible.
What I strive for is an API that is intuitive and easy to use and easy to refactor if needed. ABI backwards compatibility isn’t a requirement in my case
It seems to me that approach #2 is far more practical and clean – nearly every function will have the same API, refactoring becomes easier and it makes sense that such library provides a control block structure for user to initialize and manage through provided API.
Is there a preferred approach in such situations? I understand this is very open-ended so I would appreciate any thoughts on the matter