Notes on API Practices

December 18, 2019    api best-practices

Technique Treat customers with disdain Show customers love
1 Don’t have an API Have an API
2 Make signups difficult, users must justify their request Self-service onboarding
3 Exorbitant fees for the privilege of API access Enable API access for free or as part of an “enterprise-level” package
4 API documentation behind login page or otherwise hidden from search engines API documentation freely accessible and referenced by public search engines
5 Use a proprietary or terrible protocol Use an industry-standard protocol such as JSON:API or gRPC (
6 Permit only one API key Permit multiple API keys for each rotation
7 Tempt fate by maintaining documentation manually Keep documentation in sync with code using automated systems such as Swagger or gRPC
8 Ignore the infrastructure as code (IaC) revolution Make IaC a top priority: Provide officially supported modules for Terraform, Chef, Puppet, Chocolatey, and similar systems
9 Design APIs to be non-idempotent whenever possible Design APIs to be idempotent whenever possible