API Design Best Practices - What GoodReads is doing wrong

[Jason]

While working on our cloud ebook manager, we decided to create a C# library for the GoodReads api. Here's what we noticed: http://coderwall.com/p/u5o65a

[Grunthos]

While I agree wholeheartedly with your comments on API design, I think the overall impression from your article is that goodreads API is a failure, and would have been successful if they had followed your suggestions. Imo these interpretations are both very far from the truth.

For me the 0th and 1st laws in having a good API are:

0. Write an API. Yes, this is a tautology, but so few sites choose to make an API, and even fewer make them publicly available. Anybody who does both of these things deserves a great deal of credit.

1. Provide support for your API. I have worked on other sites with design much closer to those specified in your document, but those same sites provide zero support for developers. Emails disappear and posts get ignored. Even the best designed API is less than useless with no support.

Beyond these two steps, the rest is cake. Your document does cover several important aspects of good API design.

In summary, I can live with a very quirky API if the people behind it support it and want it to succeed.

Edit: to be clear, I think the folk at goodreads score high marks for (0) and (1) above.

[Ettore]

Thanks Grunthos, and thanks Jason for the good points. We know the API has its flaws here and there but we are committed to making it better and obviously to support it. Hopefully the new API end points being added are a little better than the old ones. For any issues, don't hesitate to post here, we all routinely monitor this group to support our developers.