[ba-ohs-talk] [Fwd: APIs Considered Harmful]
I like this article. (01)
My favorite quote:
I have learned to really appreciate the power of
the "distributed systems as stateless document exchange,"
which I believe lies at the heart of what makes HTTP so
stunningly successful. (02)
-------- Original Message --------
Subject: APIs Considered Harmful
Date: Thu, 18 Apr 2002 01:31:15 -0400 (EDT)
From: XML_in_Practice@itw.itworld.com
To: eric.armstrong@eng.sun.com (03)
XML IN PRACTICE --- April 18, 2002
Published by ITworld.com -- changing the way you view IT
http://www.itworld.com/newsletters
________________________________________________________________________________ (04)
HIGHLIGHTS (05)
* Are APIs the root of all evil or a blessing from above? This week,
Sean
explains why life might be better without them.
________________________________________________________________________________ (06)
SPONSORED LINK (07)
WEBCAST: PUT AN END TO MISMANAGED INTRANETS! (08)
Join Microsoft during a 60-minute webcast as they delve into the
inefficiencies of traditional corporate Intranets and analyze the
issues of costs, productivity loss, higher IT, and employee turnover.
Microsoft will offer you an alternative approach in the form of the
SharePoint Portal Server and the Microsoft Solution for Intranets - an
Intranet Portal Solution. View this program TODAY!!! (09)
http://itw.itworld.com/GoNow/a14724a56573a76033898a5
______________________________________________________________________________ (010)
APIs Considered Harmful
By Sean McGrath (011)
I have an uneasy relationship with APIs. Part of me thinks that the
concept of an API is the most useful abstraction since binary logic.
Part of me thinks that APIs are a root cause of a wide range of ills,
including vendor lock-in and exploding software maintenance costs. (012)
This week, I am firmly in "I don't need no stinkin' API" mode. I have
been doing some Web application development that involves uploading XML
instances to a Web server programmatically by performing HTTP POST
requests. Basically, my task was to do, programmatically, what a
browser does when it submits an HTML form. (013)
My first port of call was the truly indispensable Ethereal
(http:\\www.ethereal.com). This is a free network protocol analyzer
that allows you to monitor what is happening on a TCP/IP network. (014)
Using Ethereal, I was able to launch my browser and get to the point
where I was submitting the "Upload XML" form. I then started recording
HTTP traffic with Ethereal. (015)
When the upload was done, I was able to look at the HTTP POST request
and response pairs to figure out what my program needed to do to
emulate what the browser had done. So far, so good. I dug out my trusty
development tools, which positively ooze APIs for doing this and that
on the Web, and set to work. (016)
It was all downhill from there. Each HTTP API I tried had a different
conceptual model describing what was going on underneath. Some allowed
me to accumulate HTTP headers by tacking them together. Others provided
a hashtable interface that enforced the uniqueness of HTTP header
names. The former type did not support MIME-encoded payloads; the
latter supported MIME, but in using them I could not control the order
in which the headers were omitted, making it *very* difficult to know
if the stuff I was generating was the same as the stuff recorded in the
Ethereal traffic log. (017)
Some APIs blurred the distinction between URL-encoded parameters and
body-encoded parameters. Some handled redirects transparently, others
did not. Every one of them had a different view on cookies, ranging
from "cookies are just another HTTP header" all the way to "cookies are
the one true reason for living." (018)
After a few days of this, I gave up and went back to basics. "How hard
can it be?" I said to myself. "I have a URL, I can create a TCP socket,
I can send stuff over the wire in plain text and read stuff back in
plain text." (019)
So, I created a socket and started to send and receive stuff "by hand,"
as it were. (020)
A couple of interesting things happened: (021)
1) I had the back of the problem solved in under an hour.
2) I got to see my kids before they went to bed in the evening
because I no longer had to work till 10 p.m. (022)
I was truly shocked at how simple it all really was -- once I got rid
of the APIs and took a look at what was really going on under the hood. (023)
This experience taught me a number of lessons. (024)
Firstly, APIs are no substitute for actually understanding what is
going on in any system. In some cases -- such as complex calculations
and the like -- I can see why APIs are vital. But for things like HTTP -
- protocols -- I have my doubts. The APIs get in the way of
understanding the concepts, which are really quite simple. When the API
hits the wall -- as happened in my case -- your productivity hits the
wall too, unless you can think past the API to the underlying reality. (025)
Top amongst my doubts about APIs for things like HTTP is that HTTP,
when all is said and done, is a document exchange protocol. I send you
a document, consisting of various headers and an optional body, and you
send me back a document, also consisting of various headers and an
optional body. That's it. That is all there is to it. (026)
Secondly, I have learned that APIs can play into the hands of those who
don't really want you to understand what is going on underneath, as
that would threaten their control over your conceptual model of how the
system works. I can think of numerous examples over the years where
APIs have had this effect in the industry. (027)
Thirdly, I have learned to really appreciate the power of
the "distributed systems as stateless document exchange," which I
believe lies at the heart of what makes HTTP so stunningly successful. (028)
Fourthly, I have learned to be even more skeptical than before about
the slew of APIs doing the rounds in the XML development community. An
XML instance is just a documents, guys; you need to understand the
document structure and document interchange choreography of your
systems. Don't let some API get in the way of your understanding of XML
systems at the document level. If you do, you run the risk becoming a
slave to the APIs and hitting a wall when the APIs fail you. (029)
With an "everything is a document exchange, choreographed over time"
view of the world, one can make some interesting connections between
XML and the technologies that preceded it, such as email. Take RFC 2821
(http://www.faqs.org/rfcs/rfc2821.html) for example. It describes the
SMTP protocol. Look inside and what do you see? Essentially, an
augmented BNF (Backhaus Naur Form) description of email *documents*.
And a BNF description is? Well, it's a grammar -- a schema, if you
like, not a million miles removed from XML Schema, DTD, or Relax NG.
Formal descriptions of document structures, along with details of how
such documents are exchanged over time... (030)
The biggest conclusion I have come to is that APIs are fundamentally
good as shortcuts to getting your work done, but *only* if you fully
understand what is going on underneath. Using APIs as a substitute for
understanding what is really going on under the hood is a bad idea
which will come back to haunt you. (031)
About the author(s)
-------------------
Sean McGrath is CTO of Propylon. He is an internationally acknowledged
authority on XML and related standards. He served as an invited expert
to the W3C's Expert Group that defined XML in 1998. He is the author of
three books on markup languages published by Prentice Hall.
________________________________________________________________________________ (032)
ADDITIONAL RESOURCES (033)
Using the Ethereal Network Analyzer
http://itw.itworld.com/GoNow/a14724a56573a76033898a4 (034)
Using Ethereal
http://itw.itworld.com/GoNow/a14724a56573a76033898a2 (035)
APIs: Microsoft's Hidden Full Nelson
http://itw.itworld.com/GoNow/a14724a56573a76033898a0 (036)
XML APIs for Databases
http://itw.itworld.com/GoNow/a14724a56573a76033898a1 (037)
Understanding XML and the Java XML APIs
http://itw.itworld.com/GoNow/a14724a56573a76033898a3 (038)
XML Software Guide: XML APIs
http://itw.itworld.com/GoNow/a14724a56573a76033898a8
________________________________________________________________________________ (039)
ITWORLD.COM NEWSLETTER ARCHIVE (040)
Index of XML in Practice
http://itw.itworld.com/GoNow/a14724a56573a76033898a9 (041)
Displaying XML in Web Browsers: Theory vs. Practice
http://itw.itworld.com/GoNow/a14724a56573a76033898a6 (042)
Unicode: Confessions of a Latinate
http://itw.itworld.com/GoNow/a14724a56573a76033898a7
________________________________________________________________________________ (043)
CUSTOMER SERVICE (044)
SUBSCRIBE/UNSUBSCRIBE:
- Go to: http://www.itworld.com/newsletters
- Click on "View my newsletters" to log in and manage your account
- To subscribe, check the box next to the newsletter
- To unsubscribe, uncheck the box next to the newsletter
- When finished, click submit (045)
Questions? Please e-mail customer service at: mailto:support@itworld.com
________________________________________________________________________________ (046)
CONTACTS (047)
* Editorial: Andrew Santosusso, Newsletter Editor,
andrew_santosusso@itworld.com
* Advertising: Clare O'Brien, Vice President of Sales,
clare_obrien@itworld.com
* Career Corner: Janis Crowley, Vice President/General Manager, IDG
Recruitment Solutions, janis_crowley@itcareers.net
* Other inquiries: Jodie Naze, Senior Product Marketing Manager,
jodie_naze@itworld.com (048)
________________________________________________________________________________ (049)
PRIVACY POLICY (050)
ITworld.com has been TRUSTe certified
http://www.itworld.com/Privacy/ (051)
Copyright 2002 ITworld.com, Inc., All Rights Reserved.
http://www.itworld.com (052)
**SEND TO A FRIEND**
Share this email with a friend! Click here!
http://itw.itworld.com/GoForward/a14724a56573aSa76033898a39 (053)
SUBSCRIBE/UNSUBSCRIBE
Please click on the link below to modify your subscription, unsubscribe,
or change your email address: (054)
http://itw.itworld.com/Change-Remove/a14724a76033898a39a56573 (055)