Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: What are good reads for designing APIs?

news.ycombinator.com

Post reply on HN
Print view View original

71–80 of 101 posts

Re: Ask HN: What are good reads for designing APIs?

#71

Post by DeadReckoning »

lnikkila wrote: post #28

I really liked Building Stripe’s API and it’s sequel, Move fast, don’t break your API: http://amberonrails.com/building-stripes-api/ http://amberonrails.com/move-fast-dont-break-your-api/

Why are they versioning using dates? I know you probably wouldn't want to deploy a public API change more than once per day, but if version numbers are equally good why not give yourself the option? It also could lead to confusion about which API is newest due to UK vs US date formatting whereas a version number is unambiguous.

Re: Ask HN: What are good reads for designing APIs?

#72

Post by duncan_bayne »

It's a bit meta, but consider that building a culture that supports good APIs is every bit as important as the APIs themselves, and usually harder.

A good starting point in this area is Steve Yegge's famous platform rant:

https://plus.google.com/+RipRowan/posts/eVeouesvaVX

Re: Ask HN: What are good reads for designing APIs?

#73

Post by philbo »

neves wrote: post #33

Don't miss Joshua Bloch (from "Effective Java" fame) great presentation: How to design a good API and why it matters https://www.youtube.com/watch?v=aAb7hSCtvGw and the accompanying slides: http://static.googleusercontent.com/media/research.google.co...

+1, strongly agree.

I've recommended this talk to numerous colleagues over the years, always with extremely positive feedback. And I've re-watched it myself 3 or 4 times as a refresher before starting out on a new API.

It's easily in my top ten favourite programming talks. If anyone hasn't watched it, I can't recommend it highly enough.

Re: Ask HN: What are good reads for designing APIs?

#75

Post by infinotize »

lnikkila wrote: post #28

I really liked Building Stripe’s API and it’s sequel, Move fast, don’t break your API: http://amberonrails.com/building-stripes-api/ http://amberonrails.com/move-fast-dont-break-your-api/

When I saw this thread title, I clicked and immediately Ctrl+F'd for 'amber.' Great read in general.

Re: Ask HN: What are good reads for designing APIs?

#76

Post by puddintane »

OJFord wrote: post #61
derefr wrote: post #56

Earlier quoted context omitted.

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

Re: Ask HN: What are good reads for designing APIs?

#77

Post by MichaelGG »

JimDabell wrote: post #34

I think it depends on what type of API you'd like to design. If you're talking about REST APIs, then the best book I've come across is RESTful Web APIs by Leonard Richardson and Mike Amundsen: http://restfulwebapis.org/ It actually shows you how to do REST properly, not that shoddy knock-off REST that some people push, where you have to document all your URI structures and hard-code them in your clients. There's soli…

Why should anyone care about doing "REST properly"? I've never seen a convincing argument. I've used REST and "shoddy REST" and haven't seen much indicators in quality one way or another. In fact, far beyond the actual design is the question if they provide client code. That makes so much more of an impact.

Indeed the only real negative I've seen is people going out of their way to make it REST and in the process adding needless details, or requiring me to set a bunch of options on my HTTP request. Hint: setting a bunch of headers and a verb is not easier than passing some querystring params.

Re: Ask HN: What are good reads for designing APIs?

#78

Post by emilsedgh »

andreasklinger wrote: post #26

When doing my last bigger API i read every recommendation. Still learned a lot. Everyone has different recommendations - dont get discouraged by this. Make sure also to look into newer standards like JsonAPI if they are suitable - last time i tried to use it the tooling around it was still not strong enough and i decided to go w/ simpler custom api. Assuming it has to be a restful api (vs graphql) and assuming you wa…

Never nest data (not `post: { author: { … } }` but reference only `post: {author_id: …}`)

I'm creating a huge API on my dayjob and we have nested A LOT. So many levels of nesting, the responses have become too big.

Yet, the clients refuse to call additional endpoints and always insist on this. And it _does_ make sense for them to make 1 call and retrieve all information they need.

How does everyone handle this on REST?

(I know GraphQL is a solution.I'm wondering how people use REST API's)

Re: Ask HN: What are good reads for designing APIs?

#79

Post by erikb »

You can't learn that in a book. Use other ppls APIs, read other people's APIs, design own APIs, overcome the desire to say "FK U" to everybody who criticises your APIs, edit your APIs, rinse&repeat.

It becomes interesting once you start to use/read "hard" or "shitty" APIs. You may discover that many of them aren't either of their given labels, but that they solve really complex problems, that can't be solved (even) more intuitively.

Re: Ask HN: What are good reads for designing APIs?

#80

Post by danm07 »

The best thing to do is to start using API that other people have built. Try getting the data, see where the bottlenecks/friction points are - what things are clear and what things are not. This will put you in the shoes of someone who will physically use one. Otherwise, its all conjecture.
Post reply on HN