[Date Prev] [Date Next] [Thread Prev] [Thread Next] Indexes: Main | Date | Thread | Author

[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
________________________________________________________________________________    (04)


* Are APIs the root of all evil or a blessing from above? This week,
  explains why life might be better without them. 
________________________________________________________________________________    (06)



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)

______________________________________________________________________________    (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)


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
________________________________________________________________________________    (039)


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
________________________________________________________________________________    (043)


- 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, 
* Advertising: Clare O'Brien, Vice President of Sales, 
* 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)


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)

Share this email with a friend! Click here!
http://itw.itworld.com/GoForward/a14724a56573aSa76033898a39    (053)

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)