API Design - Matt Gemmell • Hacker News Board

I haven't had any trouble passing a null pointer and casting it. Your API is going to be expanding regularly and the more message-passing objects you create, the more message passing objects' definitions you'll have to expand as the API expands.

Re: API Design - Matt Gemmell

#5

Post by jmonegro » Thu, May 24, 2012, 5:01 PM UTC

ebun wrote: post #2

"APIs are UX for developers." This simple statement just changed the way that I think about API's.

I work so much with APIs I began to gather a list of top APIs by experience and usability. Stripe is right up there at the top of the list, everything about it is just plain beautiful.

Re: API Design - Matt Gemmell

#6

Post by smattiso » Thu, May 24, 2012, 5:19 PM UTC

This is great advice for anybody who does iOS development. If you are creating a component that is only going to be used internally in your application, it's tempting to just slap it together without really thinking about it. In the long run this really will save you time and headaches.

Re: API Design - Matt Gemmell

#7

Post by timtadh » Thu, May 24, 2012, 5:20 PM UTC

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 "touchpoints" of API design. These are sort of general guidelines and a lot less specific than the article was.

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

consistent - Naming of methods, properties and other entities should be consistent. Example if you have a method "getColor" you should not have a method "get_width" or "width" 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 "translateCoords(x, y)" you should not have a method "setTopRight(y, x)". This principle is extensible into other domains as well (such as exceptions).

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

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

discoverable - 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 "help()" command and docstrings is a good start. For web APIs consider providing an "explain" API which returns documentation.

Re: API Design - Matt Gemmell

#8

Post by [deleted] » Thu, May 24, 2012, 5:20 PM UTC

[deleted]

Re: API Design - Matt Gemmell

#9

Post by sambe » Thu, May 24, 2012, 5:34 PM UTC

Desirable qualities

    Intuitive
    Forgiving
    Frictionless

Most of this article applies equally well to humans...

Re: API Design - Matt Gemmell

#10

Post by goblin89 » Thu, May 24, 2012, 5:36 PM UTC

timtadh wrote: post #7

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 "touchpoints" of API design. These are sort of general guidelines and a lot less specific than the article was. orthologonal - 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…

A valuable advice. I'd add purposefulness, for the lack of better word. API is usually intended for some specific use cases, and it's important to communicate what these are—in documentation and in API design itself. (Although this point could be seen as an extension to your “provide examples of how to accomplish tasks” suggestion, it probably deserves its own mention.)

I'd also say that discoverability does not matter as much as documentation, IMO only very extensive APIs with lots of endpoints would actually benefit from it. I.e., in the case of web service APIs, don't waste resources on implementing complex nested endpoints with discoverability and HATEOAS when just a bit of clear documentation would do.