How We Design Our APIs at Slack
slack.engineering
slack.engineering
I also like the part about setting reasonable limits on records returned early on. That’s the kind of simple early optimization that makes sense. You can always increase limits later but it can be harder to reduce them, especially if customers have started building with your product.