I recommend this physical book: 'RESTful Web Services Cookbook'. It walks you though the rationale behind HTTP APIs and progressively using more and more of HTTP's features to build a sophisticated but elegant API.
Ask HN: What are good reads for designing APIs?
21–30 of 101 posts
Re: Ask HN: What are good reads for designing APIs?
#22I'd recommend the original REST thesis from Roy Fielding. It's a bit lower level than most of the other things mentioned here, but helps get a good feeling for what is important to achieve in a RESTful web service.
Re: Ask HN: What are good reads for designing APIs?
#23A cow helped me understand idempotency. :D http://www.restapitutorial.com/
Re: Ask HN: What are good reads for designing APIs?
#24Times really do change very fast.
Many of the comments here take API to mean an HTTP exposed API (REST), but API stands for "Application Programming Interface"
It is much more generalized than APIs designed for HTTP consumption.
Re: Ask HN: What are good reads for designing APIs?
#25You'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…
spot on my friend !!
Re: Ask HN: What are good reads for designing APIs?
#26When 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 want to create an api for multiple kinds of clients (that's the the harder part) - Here my personal TL;DR:
- Autogenerate your docs with your tests
- Do versioning in URL (easier to route/cache/etc)
- Worry about caching (a lot)
- Personalized info only in isolated namespace, rest is fully cacheable
- Never embed personalized information (eg not `{ post: { user_has_commented: true } }`
- Never nest data (not `post: { author: { … } }` but reference only `post: {author_id: …}`)
- Embed referenced objects only by whitelist
- Never nest routes (not `/posts/343/comments` but `/comments?post_id=232`) filtering tends to become more complex
- Use public feedback tools (eg github issues) for your user questions/complains - so it can become searchable for people with similar problems
hth - happy to answer some of those in detail if useful
As said - highly subjective opinions - i am sure others might disagree w/ some of the points
Re: Ask HN: What are good reads for designing APIs?
#27I'm going to take the pretentious and predictable* route here and recommend The Design of Everyday Things. It's not about REST APIs or whatever particular instance you're after, but it is more philosophical about what APIs are.
*Like a freshman preaching Rand
Re: Ask HN: What are good reads for designing APIs?
#28I really liked Building Stripe’s API and it’s sequel, Move fast, don’t break your API:
Re: Ask HN: What are good reads for designing APIs?
#29Times really do change very fast. Many of the comments here take API to mean an HTTP exposed API (REST), but API stands for "Application Programming Interface" It is much more generalized than APIs designed for HTTP consumption.
I think in this case we all had to infer context where none was provided, but you're right that the meaning has drifted.
These days the unit of work is very often some HTTP-exposed service rather than a platform library, or an interface to hardware or the like. But, I'll join your point and say there aren't too many (recent) generic resources about how to design non-HTTP APIs, since the idioms and patterns tend to be language-specific.
Re: Ask HN: What are good reads for designing APIs?
#30Casey Muratori - Designing and Evaluating Reusable Components