<story><title>API Design - Matt Gemmell</title><url>http://mattgemmell.com/2012/05/24/api-design/</url></story><parent_chain></parent_chain><comment><author>timtadh</author><text>This is a great document. Lots of detail, good recommendations. I recently gave
a short lecture on API design and came up with the following &quot;touchpoints&quot; of
API design. These are sort of general guidelines and a lot less specific than
the article was.&lt;p&gt;&lt;i&gt;orthologonal&lt;/i&gt; - Properties and methods should not overlap in functionality.
                 If two methods do sort of the same thing but differently that
                 is a design issue. They should either do entirely different
                 things or there should only be one method. Providing two is
                 confusing and can potentially lead to bugs.&lt;p&gt;&lt;i&gt;consistent&lt;/i&gt; - Naming of methods, properties and other entities should be
               consistent. Example if you have a method &quot;getColor&quot; you should
               not have a method &quot;get_width&quot; or &quot;width&quot; or any other variation.
               You should stick with one format. In the same way argument orders
               should be consistent. For example, if you have a method
               &quot;translateCoords(x, y)&quot; you should not have a method
               &quot;setTopRight(y, x)&quot;. This principle is extensible into other
               domains as well (such as exceptions).&lt;p&gt;&lt;i&gt;composable&lt;/i&gt; - Methods and functions should be reasonably composable. Instead of
               creating giant methods which do many things create small methods
               which do one thing really well. Then provide a clear way to
               compose methods together in order to accomplish a task. In this
               way methods do not have to be written which explicitly perform
               complex tasks.&lt;p&gt;&lt;i&gt;learnable&lt;/i&gt; - All design is for naught if the API is not well documented. Much
              has been written on the importance of this step but it should be
              stressed again. Good documentation can make up for any number of
              short comings in the design. So document your api, provide
              examples of how to accomplish tasks.&lt;p&gt;&lt;i&gt;discoverable&lt;/i&gt; - Hand in hand with documentation comes the ability to be able to
                 naturally discover other parts of an API. This can be provided
                 in a number of ways based on language and platform. In Python
                 providing great dynamic help via the &quot;help()&quot; command and
                 docstrings is a good start. For web APIs consider providing an
                 &quot;explain&quot; API which returns documentation.</text></comment>
<story><title>API Design - Matt Gemmell</title><url>http://mattgemmell.com/2012/05/24/api-design/</url></story><parent_chain></parent_chain><comment><author>ebun</author><text>&quot;APIs are UX for developers.&quot;&lt;p&gt;This simple statement just changed the way that I think about API&apos;s.</text></comment>