They are very valuable lessons for anyone designing API.
I sum up the 9 lessons:
- OAuth and HTTPS-only: OAuth is easy to implement on both server and client. Offloading encryption to HTTPS is a no brainer.
- 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.
- Generic structures and indirection: Wordier and more explicit JSON, but less likely to break with future changes.
- Documentation: API explorer is good. It is worth hacking up a simple documentation generation system for the endpoints.
- Timestamps as seconds since epoch: Not human-readable, but so easy to parse, and nobody has complained.
- Versioning: Sometimes, you need to take back some decisions, sunsetting certain a old version, and out with a new version. It is needed.
- Category representation: Should have
- Object consistency and level of detail: Having a "compact" and "full" representation
- Envelope: Wrap responses in a meta block