5 ms·

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 alg

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.

supergeek133 10y ago
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.
sd_sangit 10y ago
spot on my friend !!
cloudjacker 10y ago
lets look at how not to design an http API
- philgo20 10y ago
  Care to elaborate?
levbrie 10y ago
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.
derefr 10y ago
> 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.
- OJFord 10y ago
  > 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 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 https://news.ycombinator.com/item?id=6224155
  - puddintane 10y ago
    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 https://news.ycombinator.com/item?id=868102 [2] http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf http://web.archive.org/web/20090520234149/http://chaos.troll...
fapjacks 10y ago
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 https://www.twilio.com/docs/api/rest

supergeek133 10y ago

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.

sd_sangit 10y ago

spot on my friend !!

cloudjacker 10y ago

lets look at how not to design an http API

philgo20 10y ago
Care to elaborate?

levbrie 10y ago

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.

derefr 10y ago

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

OJFord 10y ago
> 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 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 https://news.ycombinator.com/item?id=6224155
- puddintane 10y ago
  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 https://news.ycombinator.com/item?id=868102 [2] http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf http://web.archive.org/web/20090520234149/http://chaos.troll...

fapjacks 10y ago

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 https://www.twilio.com/docs/api/rest