Posted a bunch of API design related tweets last year. Recapturing them here:
Does it make your life or the user’s life easier? Good API design puts the user’s first. As a lib writer the burden is on you, not on them.
The main trick of good API design is simply to use it yourself in a real-world scenario - a.k.a. eat your own dogfood. Use your own product.
API design: consider offering both a low-level API (harder to use, but no overhead) and a high-level API (more user-friendly, maybe slower).
The trick here is to provide the HL version as source code that uses the LL version. Also serves as example / sample.
API: in any case, don’t break people’s code with your new version. Don’t change the API without a good reason.
If you do, provide old functions (marked as deprecated) as wrappers that re-route to the new functions. Do. Not. Break. Your. Users’. Code.
API: have a dummy CPP file that calls all API functions (without purpose). Ensure it keeps compiling. If it breaks, you did something wrong.