Deliver the API as Direct Exposure - or bi-product ?
When an application developer want to API'lize their product, they have to make a decision. How should the third-party developers (like you!) access our system ? The history shows us a couple of interesting approaches:
- Via "Direct Exposure"
This technique let the third-party developers use the exact same functions as the product it self. Let's say that the original product uses a function OpenCertificate. Via Direct Exposure the third-party developer would use the exact same function to open a certificate.
This approach has many advantages such as; If the original application developer discovers a bug in the exposed functions, they will typically be fixed quite fast, due to the fact that the original application will suffer from the bug. If the OpenCertificate function doesn't work for the third-party developer, it probably wont work in the original application either! Another advantage are the deployment of the application. Since the API "are already there", you don't need to ship any other components but the ones already installed from the main application,
The disadvantages can also be counted! If the exposed functions are difficult to use, the third-part developers may introduce wrong parameters, or use them wrong. This may be forgiven in the function (also known as "robust") all the way up to complete havoc, leaving the user no other options than complete restart of the machine. If the error is severe, you might even have crashed the underlying data structures so hard, that recovery is not possible.
To sum up Direct Exposure we can say that this is a very direct, intravenous way to expose the application. It has it's advantages and disadvantages, but are generally powerful. They can however be difficult to program, and have the typical "Made by programmers, for programmers" feel to them.
The Lotus Notes C API uses this approach!
- Via "bi products"
This technique does not expose the real functions directly, as with "Direct Exposure" above. It rather introduce a middle layer between the real application and the third-party developer. The reasons for this approach also has its advantages: The main application developer can freely change the underlying functions and don't bother about the interface used by the third-party developers, as long as the interface (ie. function name and parameters) doesn't change. This gives the application developer a freedom to maintain the main application and it's API in different stages.
One disadvantage is that the API may live its own life, and may be forgotten during the lifetime of the main application. Since we have loose coupling between the application and the API, the developer might not feel the urge to fix bugs as fast as with Direct Exposure. Another disadvantage is that the API is often shipped as a bi-product to the main application. The bi-product is often in a form of one or more DLL files. For example will Microsoft Visual Basic need it's run time module in the form of a DLL file.
Lotus Notes use this approach for it's C++ API
