joshua stein has been operating Pushover’s public-facing API for over a decade now and thought to pass on advice for those creating a new API.

Pushover’s API might be unusual in that it is used by a wide range of devices (embedded IoT things, legacy servers, security cameras, etc.) and HTTP libraries, rather than mostly being accessed from JavaScript in the latest web browsers. It also doesn’t process sensitive financial information, so the advice given here may not be applicable to something operating like Stripe’s API.

Serve your API at api.example.com, never at example.com/api. As your API’s usage grows, it will expand beyond your website/dashboard server and need to move to a separate server or many separate servers. You’ll want to be able to move things around by just pointing its IP somewhere else rather than trying to proxy things from your dashboard server.

Accepting a slightly non-conforming API request today from someone’s ESP8266 buried in a forest might mean you’ll have to keep accepting those same non-conforming requests being made years later, often at the cost of having to implement workarounds in your web framework or server code as it gets upgraded.

Read much more in the post here.

Image by Freepik