APIs considered harmfulSam Ruby points to an article by Sean McGrath on APIs, especially on APIs involving markup languages (HTML, XML, etcetera). Very good advice here. It's worth noting that this type of discovery is possible for developers while creating new markup language specifications. It ought to be documented that way if possible. Point out the standard stuff which the API controls (and how), then point out the esoteric stuff.
Maybe I'm not as bright as a lot of people, or perhaps I simply don't have enough time. When it comes to transports, all I want to see is the data stream with enough comments to figure the rest out. I don't need 100 pages of discussion that makes my head hurt. Show me the data, now show me how to control the data. Got an error list for the API (that really helps)? Now I can get started, and refer to the verbose API docs when I have a real question.
After a bit of work with new API, I can come back and compare my mapping to the mapping in the documentation. Do they match or am I missing something? Better yet, is there some way to leverage this that hasn't been mentioned?
The SOAP documentation was like this for longer than I care to remember, way too much talking, not enough showing. Had SOAP come with working HTTP POST examples it would likely have been a heck of a lot easier to figure out. Too many pieces and parts at one time (and for people starting today it seems worse, the .jar dependencies for the Apache projects seem out of control).
Given Sams comments on yet another comment thread I am going to need to look at WSDL 1.1 again. I don't remember seeing anything that was useful for document literal XML, which we are using extensively.
3:51:29 PM 
|
