HN Explorer

Ask HN: What REST APIs, in your opinion, deserve an award?

7 points by myrloc ↗ HN
What REST APIs, in your opinion, deserve an award for an admirable quality, be it design, documentation, etc.

For example, I would given an award for documentation to Stripe's API docs (https://stripe.com/docs/api) due to its simplicity and support for their official SDKs.

The more general form of this question is: what are your favorite REST APIs and why?

3 comments

[ 2.8 ms ] story [ 16.4 ms ] thread
apotheosis-neko
I have worked with so maaaany APIs. Could definitely say my least favorite without thinking too hard. Favorite is a bit harder.

1. Github. WHY: They keep is consistent across versions and it is easy to work with.

2. Hubspot. WHY: Each object is it's own endpoint, very clear and concise. Short on mixed objects that should obviously be easily connected.

3. Mailchimp. WHY: The actual work that gets done with the API is complex while the API itself is not.

Good APIs should be clear, work as stated in the docs, there should never be a case where "logically it should work this way" but it does not.

myrloc
Curious - do you have any experience working with alternatives to REST, e.g. Github's GraphQL API?
JoshuaDavid
Twilio: consistent, well-documented, as simple as needed for the problem space but no simpler. As an example of "as simple as possible but no simpler" and also "well-documented", see "What the heck is a segment"[1]. Basically, plain SMS messages can be 160 bytes each, and if you want to send more than that, you have to send a multi-segment message, which sends multiple messages with a common header, which the receiver of the message reassembles into what looks like a single message. If you send a message with > 160 chars, or with non-GSM chars, it will "just work" but if you're optimizing for cost they still show you which encoding is used / how many segments so you can fiddle with that if you need to).

[1] https://www.twilio.com/blog/2017/03/what-the-heck-is-a-segme...