This is just as crucial as building your API properly, IMHO. I should be able to piece together my API integration from a mixture of examples, good documentation of deep features and caveats, and intuiting API methods.
For example, this API method (comes from real docs) is far from RESTful and leaves me guessing; what's the path for POST-PUT-DELETE (note, when I looked in the docs, API paths for those methods were not named POST/PUT/DELETE like this one is named get...)?
I won't rant about API design as some HN'ers have posted excellent articles on proper RESTful API design already.
Docs that are out of date (I loathe developers that don't keep API docs up-to-date), misspell in examples or have un-tested examples, or generally are confusing to navigate are ridiculously unfriendly.
For example, this API method (comes from real docs) is far from RESTful and leaves me guessing; what's the path for POST-PUT-DELETE (note, when I looked in the docs, API paths for those methods were not named POST/PUT/DELETE like this one is named get...)?
I won't rant about API design as some HN'ers have posted excellent articles on proper RESTful API design already.Docs that are out of date (I loathe developers that don't keep API docs up-to-date), misspell in examples or have un-tested examples, or generally are confusing to navigate are ridiculously unfriendly.