9 API Lessons from Foursquare Engineering Team

Foursquare is going to sunset their v1. With their new v2, they have blogged about their experience in designing API – Woulda, coulda, shoulda.

They are very valuable lessons for anyone designing API.

I sum up the 9 lessons:

1. OAuth and HTTPS-only: OAuth is easy to implement on both server and client. Offloading encryption to HTTPS is a no brainer.
2. REST lite: Resource-ful for key objects, with associated actions. Avoid deeply nested URLs. Avoid having multiple ways to do the same thing. Use only POST and GET. Avoid PUT and DELETE.
3. Generic structures and indirection: Wordier and more explicit JSON, but less likely to break with future changes.
4. Documentation: API explorer is good. It is worth hacking up a simple documentation generation system for the endpoints.
5. Timestamps as seconds since epoch: Not human-readable, but so easy to parse, and nobody has complained.
6. Versioning: Sometimes, you need to take back some decisions, sunsetting certain a old version, and out with a new version. It is needed.
7. Category representation: Should have
8. Object consistency and level of detail: Having a "compact" and "full" representation
9. Envelope: Wrap responses in a meta block