joshua stein - Advice for Operating a Public-Facing API

Joshua writes some good pointers on running your own public API from his experience running Pushover's API. I recommend reading his full post, I've distilled it down here with some of my notes.

• Host the API on its own hostname (i.e. api.example.com) to allow for separate control of IP, TLS settings, and so on. I've made this mistake before of figuring I could just use NGINX in front of everything on a single domain. Not entirely scalable.

• Account for users doing the bare minimum to get their application working, including inadvertently using non-conforming requests. Supporting them now will mean supporting them for all eternity unless you start working on a deprecation strategy. This reminded me of when I built a bot to send notifications of new posts on a subreddit. I created the URL for the post by inserting the subreddit name returned by the API. Within the URL I included "/r/" and the API also returned "/r/" before the subreddit name, which mean the URL generated had "/r/" twice. This still worked for a while before Reddit decided to reject those requests and I had to adjust my code. Had to dig through the Discord message archives for that one. Joshua also gives an example of not being too stringent:

Pushover's API has a message size limitation of 1,024 characters. If the message parameter is larger than that, I could reject the request because it's not correct, but then the user's message is lost and they may not have any error handling. In this case, I truncate the message to 1,024 characters and process it anyway [...] The user still receives something, and if they care that it's truncated, they can properly implement continuation or smarter truncation.

• Use API tokens were possible for authentication, and make them easy to rotate.

• Include a unique ID with every request and ask for them when providing customer support.

• Assume humans will read your error messages, make them descriptive. Please, this.

• Keep up with user failures, Pushover's API "short-circuits" the API logic after a set number of 4xx errors with a 429 response for an hour, along with a descriptive message. Use the API tokens to map the erroneous requests with a user and notify them via email.

• Prefix any tokens you create ot help sorting out random strings. This is one thing I've seen used a lot but never considered doing myself until reading this.