
Ask HN: What REST APIs, in your opinion, deserve an award? - myrloc
What REST APIs, in your opinion, deserve an award for an admirable quality, be it design, documentation, etc.<p>For example, I would given an award for documentation to Stripe&#x27;s API docs (https:&#x2F;&#x2F;stripe.com&#x2F;docs&#x2F;api) due to its simplicity and support for their official SDKs.<p>The more general form of this question is: what are your favorite REST APIs and why?
======
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...](https://www.twilio.com/blog/2017/03/what-the-heck-is-a-segment.html)

------
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?

