1. I pretty much agree. But I think it can be better summed up by saying, “Think about what API you’d like to work with if someone else had written it. Further, think about the information you’d like to know before attempting to use the API.”

    If you ask yourself these two questions as you’re developing your API, then the API should be much easier to use and the documentation should almost write itself. At the very least, it should lead to inline documentation that can be parsed with Doxygen which will actually be usable by other people (i.e. _not_ the Groovy/Grails documentation).

    A project that I think does this well is AFNetworking (https://github.com/AFNetworking/AFNetworking). On the other end, we have libssh2 (http://www.libssh2.org/). Both are great APIs (for the most part), but only one is a joy to use; and it’s not the one with shitty documentation.


  2. Oh, and there’s another article that I really like on this topic — http://mattgemmell.com/2012/05/24/api-design/ . He is using his Objective-C experience for examples, but it applies to anything.


Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.