API Development Tips

Organisations who are paying attention already know they need to have an open web API, and many already have under development or in the wild. Make sure you haven’t been caught by the pitfalls of many early API releases.

Multiple points of failure:

• Back-end systems: db servers/caches, hardware failures, etc.
• Interconnections: router failures, bad cables, etc.
• External Dependencies: fail whales, random cloud latency, etc.

The 5 tips

Test it all

1. Unit test are not enough, they are just the beginning.
2. Test what users experience. Perform end-to-end black box tests.
3. Replay your access logs. Very accurate.
4. Validate return payloads. A stack trace is not valid XML.

Plan for future versions

1. Versions are not sexy/semantic (but do it anyway).
2. Announce versions often.

Embrace standards

1. APIs are better when predictable.
2. Standard approaches mean tools.
3. Avoid uncomfortable migrations. No one wants an OAuthpocalypse.

Monitor everything & be honest

1. Trends are your friend.
2. Users are not your early-warning ops team.
3. Be open and honest, or your users will tweet that your API sucks!

Fail well

1. Well-formed errors win friends and makes users more tolerant to failure.
2. Make monitoring easy.
3. Don’t punish everyone. Determine who gets hurt most by failures.

Watch the video here: Understanding API Activity by Clay Loveless