Embed Size (px)
Citation preview
What’s an API"Application" (?) "Program Interface"
a collection of functions, data types, protocols, events, &c, whereby any software system X can interact with a given software system YY can be: a library, a framework, application, operating system, web site...Y's developers are typically responsible for designing and implementing the API
2
What's an Antipatterna category of counterproductive behaviors that are often, systematically repeated
can be: in business processes, project management, design, programmingan anti-pattern write-up should include:
root causes (why did it seem a good idea at the time?)effects (why it's actually a bad idea)interactions (how it helps or damages other patterns or antipatterns)refactoring (suggestions for fixes)
3
API Design Antipatternsthe very worst APIDA: not having any API
the worst API's the one that's not therethe second worst: not having any design
the API that "just happened""none" is too few; can there be too many?"fear of commitment": to design→to chooseinconsistency issues in APIs...but wait, there's more...!
4
More kinds of APIDAsWon't do these justice, but...:"In medio stat virtus": pairs of extremes
what language(s) to support?excessive language dependenceexcessive language INdependence
what about standard protocols/formats?ignoring them blythelyrigidly, lavishly letting them "drive"
debugging, error messages, documentationperformance-related APIDAs
5
The very worst APIDAthe worst API is -- no API at allcheck e.g. stackoverflow -- most common Q:
about spidering and scraping websitesabout simulating keystroke & mouse acts
some of those Qs are about system testingmost of them are about "missing APIs"
the APIs may not actually be thereor they may be undocumented
which is almost as bada bad, weak API is still better than no API
6
Why "no API" is badpeople DO need an API
whether you supply it to them, or notso, they're gonna "scrape" your UI
assuming you have an alleged one;-).useless load on your system
rendering things that they then ignoremakes their lives miserable
every cosmetic change breaks themgives your competitor a nice entry!
7
What to do insteadOffer an API! "Pick an API, any API"...Even a simple, weak one's better than noneDocument it!
keeping it hidden is ~ not even having itto reduce workload, think _examples_
Keep docs updated!wrong docs are almost worse than none
8
If you're an unwilling APIerMake life easy on yourself AND the users:Follow the yellow-brick road of easy life and little actual work (if any):
for web apps, REST & JSONfor Windows apps, COMfor Mac apps, "Applescript"...wish there was ONE similarly broad answer for Linux apps too... ah well!-)
9
The accidental API that would be an "interface" that was never actually designed as such
more common than you'd thinkdesigning an interface for proper program access is hard (though interesting) work"but wait, we already have one!"
often what the UI uses to the backendsometimes (dep. on app. area) the DB
"let's use that one -- look, ma, no work"!-)
10
Why "no design" is badif you haven't designed what you're exposing exactly in order to expose it......then what you're exposing are internal implementation issues!what happens when you want to change the implementation's details?
you either forego the improvements you're foreseeing w/reimplementing,or break your clients,or shoulder forever the burden of dual implementations (real one and API)...
11
What to do instead
THINK ...about your API
FORGET...your implementation
12
Wtdi: ThinkTHINK about your API!
"if I was an outside programmer, what would I want to be doing? And, how?"ideally, don't just think: walk a mile in their shoes (e.g. your auxiliary scripts...)
13
Wtdi: ForgetFORGET about your current implementation
or, think about at least 2-3 alternative ones you might want to try in the futurewhat's common to ALL of them?what would change w/every implementation is "an accident", and somewhat irrelevant to your APIwhat stays the same is "the substance", what really must be in the API
14
Wtdi: why?isn't this think/forget business a lot of work...?yes, some -- BUT...
the ROI's amazing!not only does it enhance your API,the insight it gives on your overall design can sometimes be amazing.+: a strong API helps you properly divvy up the system (not too much stuff "in the core" if it can be "outside"!)
15
Too many cooks APIszero APIs is too fewfour is too manysomewhere in-between, probably one (maybe, conceivably, two) is the sweet spotroot cause #1: transition
esp. from a "not-really-designed" APIor, between technologies/platforms
root cause #2: unwillingness to decidecfr the "commitment issues" APIDAs
root cause #3: org.structure (in firms)
16
Why "many APIs" is badextra work to support all of them
w/o real benefit to the user,w/o real benefit for refactoring either
can be confusing to the user (must learn them all and choose/pick one?)
sometimes you can perform task A in one API, task B in another, but in neither can you do both needed tasks
of course, API transitioning/versioning is a very hard problem (no silver bullets here)
17
What to do instead"LAYERING" APIs is OK
ONE lowest-level API -- exposing all the nuts and bolts of the system's logical architecture (not implementation)it's OK if it's user-unfriendly, hard to use, a bit underdocumented, &c
as long as it's full-power, high-performance, transparently debuggable
because all OTHER APIs (one or more) are built entirely ON TOP OF the lowest-level one (no system internals involved)
18
Fear to decideAKA, the "let's do both!" syndrome
19
The "Let's do both!" APIDAwhy is it bad?
to DESIGN is to DECIDE, i.e., to CHOOSEoh boy, that's scary
am I going to be ACCOUNTABLE for it?I am not worthy (to decide) -- do both
management-structure / employee empowerment problems (often)wishy-washy programmers (more rarely)
20
"fear to decide" exampleHHANDLE WINAPI CreateFile(
__in LPCTSTR lpFileName, __in DWORD dwDesiredAccess, __in DWORD dwShareMode, __in_opt LPSECURITY_ATTRIBUTES lpSecurityAttributes, __in DWORD dwCreationDisposition, __in DWORD dwFlagsAndAttributes, __in_opt HANDLE hTemplateFile); vs int open(const char *pathname, int flags, mode_t mode);
21
To decide is humanQ to Ken Thompson:
"if you were to design Unix all over again from scratch, what would you change"?
Ken's A:"I'd spell "creat" with a trailing E"
Perfection is not of this worldbut that's not an acceptable excuse for "not even trying"
22
What to do insteadhave courage ("grow a spine")work in environments where failure (and honest acknowledgments of, and fixes to, it) is not punished, but *encouraged*
"fail -- but, fail fast!"AKA -- empowering environments
you're human -- deal. You WON'T "get it right the first time".
Launch, and iterate"Rough consensus, and running code"!-)
23
Inconsistency APIDAsargument ordering
foo(widget, value) vs bar(value, widget)lexical issues (under_score, MixedCase)
this_one(foo) vs TheOther(bar)nomina sunt consequentia rerum (verbs too)
RemoveThis/DeleteThat/EraseYonder/...plural vs singular: CommitTransaction vs RollbackTransactions (both w/1+ targets)SomeVeryDetailedSpecificName(x)/blah(y)acronyms: HttpConnect/HTTPSendQuery
24
Why inconsistency?too much Ralph Waldo Emerson?-)
but that's against a _foolish_ consistencypeople, ideas change over time
so do APIsmaybe CommitTransaction used to take only one target, then grew to take 1+
different people on the same project conceptualize (thus name) the same thing in slightly different (inconsistent) ways
25
What to do insteadestablish a "data dictionary" (not just about data: "verbs" too!) w/1-1 mapping of words to/from the concepts in the SW system
when a new concept arises, put it with the appropriate word in the DD _first_
before you name any API entry!cost: a little bit more work to coordinateadvantages: not just to "external users" of the API -- like all coding conventions, once established it _saves_ decision overhead!
26
In medio stat virtusnavigate very cautiously between pairs of "extreme" positions esp. in underlying technology choices. For example...:
what prog. language(s) to support and how closely to adhere to their "style"s?what protocols (esp. platform-standard or cross-platform standard ones) &c?
extremism is simpler, sharper, attractivebut it never works as well as balance, good taste, and moderation!-)
27
Prog.language support"sure we have an API... it's in BrainFork!"
whatever language(s) you've chosen to implement your SW system,there's no good reason to foist it on everybody else who wants to use your system's API!e.g.: avoid language-specific data interchange formats in your API (for example, no Python "pickles" please!)
"you can program Fortran in any lang."...but you shouldn't HAVE to!-)
28
Standard-protocol supportwhy use Yet Another data format?
isn't JSON or YAML good enuf x ya'?or CSV, FITS, HDF, netCDF, SAIF... (&c)?you'd better have a darn good xcuse!-)
if on the web, why not ReST? If not (yet) on the web, why not ReST _anyway_?if on Windows, why not COM?if on Mac, what about Applescript?more generally -- CORBA and other RPC standards -- why not _those_?
29
Debugging, errors, docsyou make an API → somebody will (one hopes!-) be _developing_ with/on it
they'll make mistakesso will yougood debugging support is a mustopen-source helps, does NOT suffice
error messages such "an error was encountered" (!)...docs are hard to write, but precious
at least provide COPIOUS examples!
30
Performance issuesa performance-incorrect API can kill performance in many, many ways, e.g.:
excessive "make-work" in building / dismantling objects unnecessarilyexcessive "round trips" through lack of "batching" facilitiesimproper support for threading/distrib.no or inferior support for async access
e.g.: mandatory callbackstoo-picky error-diag timing guarantees
31
Q & Ahttp://www.aleax.it/pycon11_adap.pdf
32
? !
![v1_CP3423 - Design Patterns applied to Autodesk® Inventor® API[1]](https://img.pdfslide.net/doc/110x75/547f1fce5906b5a1718b4781/v1cp3423-design-patterns-applied-to-autodesk-inventor-api1.jpg)
