I’ve done a fair bit of work with external APIs. It’s generally a fairly frustrating process. So I’ve collected a list of best practises. Some of these are shamelessly stolen from colleagues.
Some of these are a bit ‘heavy’ and not appropriate for all circumstances. This isn’t a checklist to follow blindly, it’s just a list of some good ideas I’ve picked up.
1. Logging
Log all calls going out and all incoming responses along with dates & times. Any logging should occur as close to the boundary as possible. This is to ensure that you remove as many layers of abstraction. For example if making webservice call, you would want to log the raw request & response, not a serialised version of the data you send.
Logging will help answer questions like:
- Response times, current and historical
- Is the API still available & responding?
- Has something changed at the remote end?
- Have we correctly translated internal data to external calls?
2. Mock the API
When trying to develop or test something that depends on an external API, you’ve got a huge dependency on that API. Development and testing can stall if that external API is unavailable. This is also an issue with intermittent faults. A lot of time can be wasted on trying to identify that that API is unavailable or is not working.
If the API has a test environment to work against, typically this is less stable than the production environment. Updates are shipped more frequently, issues are addressed more slowly than the production environment. Response times are also typically slower, as the environment is rarely provisioned like production.
Mocking the API protected you from all of these. Typically this means capturing known good responses. When the mock API is enabled return, these known good responses. This can be extended further to trigger specific error conditions when certain data is passed in, eg a specific customer name will trigger a duplicate name error.
You will need a simple way to switch the mock API on/off, eg a simple config file change.
3. Write Functional tests of the API
This might seem a bit overboard, but doing this can save a huge amount of time. Typically we end up doing this sort of testing manually, but it is worth doing this more systematically.
Writing functional tests helps explore the limits of the API. It can help expose bugs in the API and clarify things that might be unclear from any documentation. It can help to benchmark performance. It can also be a great source of data for mocking the API.
It can also be a great source of protection from changes in that API. If something fails, you can simply run the functional tests to verify whether anything has changed.
uberconcept - David Cameron's Blog 