https://pavanyara.com/tags/best-practices/Recent content in Best-Practices on Pavan YaraHugo -- gohugo.ioen-USpavan.yara@gmail.com (Pavan Yara)pavan.yara@gmail.com (Pavan Yara)Pavan YaraWed, 18 Dec 2019 22:21:54 +0530https://pavanyara.com/blog/api-practices-1/Wed, 18 Dec 2019 22:21:54 +0530pavan.yara@gmail.com (Pavan Yara)https://pavanyara.com/blog/api-practices-1/<table> <thead> <tr> <th>Technique</th> <th>Treat customers with disdain</th> <th>Show customers love</th> </tr> </thead> <tbody> <tr> <td>1</td> <td>Don&rsquo;t have an API</td> <td>Have an API</td> </tr> <tr> <td>2</td> <td>Make signups difficult, users must justify their request</td> <td>Self-service onboarding</td> </tr> <tr> <td>3</td> <td>Exorbitant fees for the privilege of API access</td> <td>Enable API access for free or as part of an &ldquo;enterprise-level&rdquo; package</td> </tr> <tr> <td>4</td> <td>API documentation behind login page or otherwise hidden from search engines</td> <td>API documentation freely accessible and referenced by public search engines</td> </tr> <tr> <td>5</td> <td>Use a proprietary or terrible protocol</td> <td>Use an industry-standard protocol such as JSON:API or gRPC (<a href="https://grpc.io">https://grpc.io</a>)</td> </tr> <tr> <td>6</td> <td>Permit only one API key</td> <td>Permit multiple API keys for each rotation</td> </tr> <tr> <td>7</td> <td>Tempt fate by maintaining documentation manually</td> <td>Keep documentation in sync with code using automated systems such as Swagger or gRPC</td> </tr> <tr> <td>8</td> <td>Ignore the infrastructure as code (IaC) revolution</td> <td>Make IaC a top priority: Provide officially supported modules for Terraform, Chef, Puppet, Chocolatey, and similar systems</td> </tr> <tr> <td>9</td> <td>Design APIs to be non-idempotent whenever possible</td> <td>Design APIs to be idempotent whenever possible</td> </tr> </tbody> </table> <ul> <li>via Thomas A. Limoncelli&rsquo;s excellent <a href="https://queue.acm.org/detail.cfm?id=3375635">ACM queue column on APIs</a></li> </ul> 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 (https://grpc.io) 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

• via Thomas A. Limoncelli’s excellent ACM queue column on APIs

]]>