4 ms·

The title is misleading because this is focused on Android, but the title seems to imply generic API design pitfalls

yeukhon 11y ago
there's Apple. It is using Android as an example. I am pretty sure a lot of libraries do the same. To be more precise, the 6th is more likely for any GUI building toolkit out there. pretty much every single one of them end up a dozen of lines just to build a single thing.
gregmac 11y ago
The last half definitely devolves into Android API-bashing. The first half does generally apply to most APIs. The main issue with most APIs boils down to documentation. Document it well, and it will largely be usable. This means everything from cross-references ("If you are trying to do X, ThisOtherMethod may be a better fit") to examples, and also extends to the API itself (good naming, and discoverable methods). Most developers using your API do not live in your API -- they live in their application domain. So you need to put effort into ensuring jargon is explained, the API is discoverable, and basically they can use the API easily, and get on with their application. I really like the idea of thinking of API design in terms of Developer Experience (DX), in the same way that user interface designers consider User Experience (UX) about much, much more than simply the layout and colors.
- ascagnel_ 11y ago
  > Document it well, and it will largely be usable. And a simple, easy-to-use API will also be comparatively simple to document. If you're at the point where writing documentation is hard, that's strong code smell that something is amiss.
  - laveur 11y ago
    Agreed! The API should basically document itself. If you have to provide long examples of how to do something then there is a good chance the API isn't that good. Easy to use for developers makes a platform more stable and produces better quality apps, IMHO.
erydo 11y ago
To be fair, Android has a hugely disproportionate number of API WTFs to choose from. It's an absolute mess.

there's Apple. It is using Android as an example. I am pretty sure a lot of libraries do the same. To be more precise, the 6th is more likely for any GUI building toolkit out there. pretty much every single one of them end up a dozen of lines just to build a single thing.

gregmac 11y ago

The last half definitely devolves into Android API-bashing. The first half does generally apply to most APIs. The main issue with most APIs boils down to documentation. Document it well, and it will largely be usable. This means everything from cross-references ("If you are trying to do X, ThisOtherMethod may be a better fit") to examples, and also extends to the API itself (good naming, and discoverable methods). Most developers using your API do not live in your API -- they live in their application domain. So you need to put effort into ensuring jargon is explained, the API is discoverable, and basically they can use the API easily, and get on with their application. I really like the idea of thinking of API design in terms of Developer Experience (DX), in the same way that user interface designers consider User Experience (UX) about much, much more than simply the layout and colors.

ascagnel_ 11y ago
> Document it well, and it will largely be usable. And a simple, easy-to-use API will also be comparatively simple to document. If you're at the point where writing documentation is hard, that's strong code smell that something is amiss.
- laveur 11y ago
  Agreed! The API should basically document itself. If you have to provide long examples of how to do something then there is a good chance the API isn't that good. Easy to use for developers makes a platform more stable and produces better quality apps, IMHO.

erydo 11y ago

To be fair, Android has a hugely disproportionate number of API WTFs to choose from. It's an absolute mess.