What to know before you implement public-facing APIs

Oof. There’s some okay advice mixed in here, but I wouldn’t recommend this to someone actually working on their first public API. The whole introduction reads like lightly edited AI generated slop.

Since this is tildes, I’ll try to be constructive. A few points of feedback on the article:

1. Cover some security basics: what is authentication and authorization, why are they important, and what are some common security pitfalls to avoid? The OWASP “top ten” list is a good resource.
2. The act of versioning isn’t actually very hard, but knowing what is a breaking change vs. backwards compatible is much more tricky. Talk more about how to reason about and detect breaking changes. Also, sticking version numbers in individual payloads is not going to end well.
3. API frameworks can help address a lot of these challenges. Link to some popular frameworks for different languages and protocols.
4. Talk about reasons and tradeoffs for different protocols and API conventions (REST, gRPC, graphql, etc)
5. Mention a few techniques for documentation like OpenAPI. Also related to the point about frameworks.
6. Link to an external resource that covers how to host, scale, and monitor a backend service. This is a huge topic, but it makes sense to at least talk about choosing between a serverless offering, a lower level container orchestrator, or simple “rent a server” IaaS platforms.
7. Maintaining client libraries that other engineers use to consume your APIs is an option which can save your users lots of time, clarify correct usage patterns, and help reduce the impact of protocol level breaking changes. Lots of API frameworks can help generate client libraries.
8. Run the final edit through a grammar checker before publishing.