Ask HN: What are good reads for designing APIs? • Hacker News Board

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

#31

Post by cloudjacker » Wed, Aug 10, 2016, 5:36 PM UTC

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…

lets look at how not to design an http API

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

#32

Post by niftylettuce » Wed, Aug 10, 2016, 5:37 PM UTC

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/

Amber rocks.

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

#33

Post by neves » Wed, Aug 10, 2016, 5:50 PM UTC

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

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

#34

Post by JimDabell » Wed, Aug 10, 2016, 5:52 PM UTC

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 solid examples that you build upon throughout each chapter, and jumping off points to standardisation work like JSON-LD etc.

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

#35

Post by djuang1 » Wed, Aug 10, 2016, 5:54 PM UTC

Check out http://raml.org/

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

#36

Post by jamesxv7 » Wed, Aug 10, 2016, 5:54 PM UTC

danpalmer wrote: post #22

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

Definitely, it is a great read.

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

#37

Post by b0sk » Wed, Aug 10, 2016, 5:58 PM UTC

a bunch of API design guidelines flow from Scott Meyer's famous maxim "Make interfaces easy to use correctly and hard to use incorrectly."

http://www.aristeia.com/Papers/IEEE_Software_JulAug_2004_rev...

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

#38

Post by mordocai » Wed, Aug 10, 2016, 5:58 PM UTC

I thought https://apisyouwonthate.com/ was pretty good, assuming REST API.

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

#39

Post by levbrie » Wed, Aug 10, 2016, 5:59 PM UTC

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…

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.

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

#40

Post by mandeepj » Wed, Aug 10, 2016, 6:11 PM UTC

API could be in any form - be it a dll lib, wcf or rest so I am pasting a resource for each.

1. Restful API with WCF - https://msdn.microsoft.com/en-us/library/dd203052.aspx

2. Restful API using WebAPI - https://github.com/Microsoft/api-guidelines/blob/master/Guid...

3. API via dll - https://www.amazon.com/Framework-Design-Guidelines-Conventio...