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

61–70 of 101 posts

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

#61

Post by OJFord »

derefr wrote: post #56
ccallebs wrote: post #15

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…

> 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

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

#62

Post by OJFord »

pbreit wrote: post #58
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/

The amount of versioning that Stripe does makes nervous. Is that a good practice?

As long as they adhere to the second part of their slogan, and "don't break [the prior versions of] [their] API", it's great.

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

#63

Post by misterbwong »

pbreit wrote: post #59
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…

Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?

This is one issue I struggled with in my last API design. I generally like the /comments?post_id=232 format but in many cases it's not intuitive. Especially when the sub-resource (i.e. comments) is only ever referenced in with a parent resource (i.e. posts).

This is a bit of a contrived example but with a structure like /comments?post_id=232, a developer might mistakenly assume comments are independent resources and not explicitly tied to posts when, in reality, there are can be no comments without posts. In this case, /posts/343/comments is much more intuitive.

The way we ended up handling it was forcing ourselves to limit sub-resources to a maximum of 1 level deep. So /posts/343/comments was allowable but something like /posts/343/comments/23/author was not allowed.

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

#64

Post by caseysoftware »

I'm horribly biased as one of the co-authors, but check out: http://TheAPIDesignBook.com

It documents a number of things we've learned building, using, and supporting APIs at Twilio, major banks, major hotel chains, and others. It's 100% driven by practices in the wild, not academic or theoretical info.

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

#65

Post by friendzis »

pbreit wrote: post #59
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…

Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?

Probably yes, the former not only "looks better", but is possibly easier to use in a view. Just spawn two delegates with `$post_path` and `pathcat($post_path, 'comments')` and be done with it.

However, the argument being made here is that you may not want to expose post comments as sub-resource of a particular post, but rather as completely separate resource.

And there is a point to that. Suppose you serve the post content as a static content, and comments from some application (octopress + disqus style). The latter format allows you to route anything matching `^/posts/(.*)` directly at web server level without touching application server at all. If you decided to use the former, then your infrastructure becomes dependent on your API structure. Not very nice :)

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

#68

Post by Perihelion »

caseysoftware wrote: post #64

I'm horribly biased as one of the co-authors, but check out: http://TheAPIDesignBook.com It documents a number of things we've learned building, using, and supporting APIs at Twilio, major banks, major hotel chains, and others. It's 100% driven by practices in the wild, not academic or theoretical info.

Having just picked this one up, I can confirm it's actually worth a read. It's short but full of information that will help you design better APIs even if you've already done it.

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

#70

Post by friendzis »

misterbwong wrote: post #63
pbreit wrote: post #59

Earlier quoted context omitted.

Wouldn't most people disagree with: "not `/posts/343/comments` but `/comments?post_id=232`"?

This is one issue I struggled with in my last API design. I generally like the /comments?post_id=232 format but in many cases it's not intuitive. Especially when the sub-resource (i.e. comments) is only ever referenced in with a parent resource (i.e. posts). This is a bit of a contrived example but with a structure like /comments?post_id=232, a developer might mistakenly assume comments are independent resources and…

In my view, arbitrary limits are also not too intuitive :)

Problem with nesting is that very rarely your resource classes will make an acyclic graph. Even in your example '/posts/343/comments/23/author' resource class AUTHOR may be a child of either comment or the post itself. And if a user wants to view all posts by particular author? Intuitive use might as well be '/posts/343/comments/23/author/posts/123/comments' ad infinitum :)

Such problems can be solved by providing an endpoint for each distinct resource class and making it search provider. In your example case 3 endpoints are needed: /post, /comment, /author, all accepting other two as search parameters, e.g. /author?comment=123456 or /author?comments|id=123456 (inspired by FHIR).

Post reply on HN