Guidelines for writing an XML API

[Andrew 2006]

Could anyone point me in the direction of some:
- guidelines or
- recommended standards or
- tutorials
for creating an XML API?

I want to create an API for interacting with a server and would like
to know things like:
- how to handle handshaking
- architecture tips to make the api more maintainable, etc

Many thanks

Andrew

 

[Andy Dingley]

for creating an XML API?

Don't.

We've already got generic XML APIs (XML-RPC and SOAP for starters).
Don't create yet another one.

If you want to create some schema for exchanging information with XML,
then do it by defining messages that are passed through one of these
existing low-level APIs. Don't start re-inventing concepts like
handshaking.

If you _must_ re-invent some of this, at least do a literature search
first and become familiar with how SOAP already solves this (maybe
even the old 1999 simpler SOAP standards too) and look at XML-RPC for
a good example of how not to design things and how not to document
what you've designed afterwards.

 

[Andrew 2006]

We've already got generic XML APIs (XML-RPC and SOAP for starters).
Don't create yet another one.

I don't think I've explained my question very well and perhaps have
not used the terms "XML API" and "handshanking" correctly.

I intend to use XML-RPC or SOAP to send and receive messages.

I want to define a set of XML messages that clients can send to my
server to perform various functions. To start off with:
1) Initialising a connection with the server and retrieving a client
ID from the server.
2) Retrieving data from the server using this client ID.

Just want some basic getting started tutorial, which hopefully points
out common design pitfalls etc.

Many thanks

Andrew

 

[Joe Kesselman]

Just want some basic getting started tutorial, which hopefully points
out common design pitfalls etc.

http://www.ibm.com/xml has 45 different tutorials and articles in the
SOAP category, ranging from basic to specific applications to specific
tools and including XML-RPC... and has articles on most of the other XML
techniques/technologies which underlie and support SOAP, if you need
those as well (which it sounds like you may).

 

[Volker Hetzer]

Could anyone point me in the direction of some:
- guidelines or
- recommended standards or
- tutorials
for creating an XML API?

I want to create an API for interacting with a server and would like
to know things like:
- how to handle handshaking
- architecture tips to make the api more maintainable, etc

Have a look at http://www.xml.com/pub/a/2004/12/01/restful-web.html .
I can't suggest any books but I have ordered
http://www.oreilly.com/catalog/9780596529260/ .

The approach is a radically different one but is supposed to lead
to services that can be consumed much easier, need less documentation
(basically just the hierarchies) and, most of the time, don't even
need state keeping via cookies or other mechanisms.

Lots of Greetings!
Volker

 

[Andrew 2006]

Thanks Volker that's exactly the type of thing I was after!

Andrew