Hacker News Reader

Comment by ccallebs | Hacker News Reader

You'll notice in this thread that (at 9 comments in) there are no repeated recommendations. If the question was "What are some good reads for learning about algorithms?" you'd probably see the same handful of books being praised by everyone.

Don't be overwhelmed by this though -- API design isn't an exact science. It's also very opinionated.

Personally, I would just start reading actual API documentation (GitHub is a great place to start -- their API is a joy to work with). Find things you like and don't like about it and try to figure out why those decisions were made.

View on HN

> I would just start reading actual API documentation (GitHub is a great place to start -- their API is a joy to work with)

This would be a good related subthread: links to API docs for what people consider to be both great, and terrible, APIs.

> This would be a good related subthread: links to API docs > for what people consider to be both great, and terrible, > APIs.

At least the great part has happened:

https://news.ycombinator.com/item?id=867972

There was one _much_ more recently (a week or two ago), but funnily enough the only one I can find is ~2.5k days old..

Related - best documented:

https://news.ycombinator.com/item?id=6224155

I liked this recommendation a lot by vibhavs [1] (in your first link). Found the pdf thru Wayback machine [2]. Had a lot of really good tips to keep in mind.

[1] https://news.ycombinator.com/item?id=868102

[2] http://web.archive.org/web/20090520234149/http://chaos.troll...

Agreed. Find APIs you like to work with, think about WHY you like to work with them.

People get into really philosophical discussions around versioning, resource structure, etc... but in reality think about what makes you like the APIs you like over another alternative. Then think about what you would do to make it even easier to use/integrate with.

There also with some APIs is the tradeoff of easy integration and long-term flexibility.. things like that.

On that point, after you've read whichever of the many great recommendations you end up reading, don't get discouraged if you end up having to scrap the first several APIs you build. Part of the reason building APIs is so opinionated is that it's so difficult to do it well. Look at the API documentation for a bunch of different Google projects. Some of them are absolutely abominable. Others are quite good. Algolia has great documentation. When you get it wrong, you'll know. And that's all you really need to make sure you do better next time.

I really enjoy working with Twilio's API [0]. Their documentation is great. It includes an ample number of examples. The API is also extremely easy to use.

[0] https://www.twilio.com/docs/api/rest

lets look at how not to design an http API

Care to elaborate?

spot on my friend !!

Reply on news.ycombinator.com