A new project has prompted me to investigate the trading APIs belonging to a number of Bitcoin exchanges. It's been a fun few weeks and I've learned a lot about an area I've never really watched in the past.
However, as expected it's not all been rainbows and unicorns. At least one exchange has a public API which does not even pretend to work, and most fall into a series of common traps. Hopefully I can use the following notes to design better APIs myself:
- Documentation and consideration of error handling must be foremost in your mind. A developer needs to know the exact procedure for discovering error scenarios and presenting them to the user. This must be consistent across all calls, in all scenarios; do not drop it for unauthenticated calls.
- If you have any value which represents a time you must include timezone information. This data should not simply be documented as a specific constant timezone so as to allow for future changes or the odd implementation mistake. There are a number of well defined standards which have wide traction. Use them.
- For anything finicky, such as authentication, you should be very very precise in the description of the required algorithm. At a minimum this needs a concrete executable example, and should include a step-by-step description of the whole process.
- Don't add complexity unless you can outline the specific benefit. Seemingly simple things like an extra base64 encode may not add anything of value, but may provide a sufficient burden to a taxed developer that they may prioritise something else. I'm looking at you BTC China.