Unlike other “Busy Developer’s Guide"s I’ve seen, this one will be really concise, for people who are really busy. Being busy, I haven’t really kept up with this stuff myself, and the following are sort of guesses. Lemme know if they’re wrong.

Some concepts

Syntax” is like grammar. It concerns only whether a document follows the grammatical rules or not, e.g. “capitalize the first letter of sentences”, etc.

Semantics” is the meanings which you attach to the things in the document.

For an example of the difference between them: the sentence “Colourless green ideas sleep furiously” is fine syntactically, but needs some help in the semantics department.

A “Protocol” specifies the form of data which travels “on the wire”, that is, the specific form of the data being sent over the internet.

An “API” specifies the interface that an application uses to communicate with some service, usually a set of callable functions with parameters and definitions of what they return.

APIs and protocols are similar; to a developer, they both define a set of names that you use when interacting with some other program that does things for your program. The difference is whether or not the specification is telling you the form of data going over the internet. Also, usually APIs are language-specific whereas protocols are language-independent.

Basic stuff

A URI is a fancy term for a URL, although there are those who will disagree. It has the philosophical implication that the URI is “just an identifier”, and that there might not actually be any document at the given location. For example, I might say, “Hi, my name is Bayle Shanks, and my URI is “www.fake.name/Shanks/Bayle/TheOneWhoLivesInSanDiego”. If you type that into your web browser you probably won’t find a web page there. But, that URI can still be used as a less-ambiguous identifier for me (compared to “Bayle”, although in my case that’s not too ambiguous as it is).

When a URI is being used as a globally unique, persistent name, it is called a URN. When it is being used as a network location, it is called a URL. A URI can be both a URN and a URL.

XML is a format for formats, i.e. a format for the syntax of a generalized family of HTML-like markup languages.

DTD (“document type definition”) is a format for actually defining the syntax of a customized HTML-like markup language.

For example, you might use an XML DTD to define another language which permits documents with stuff like <transaction name="bought socks"><amount>$10</amount></transaction>. The DTD would essentially say things sorta like, “This language has an element called “transaction”, which has a attribute of type “name”. Within a “transaction” element, you can have an “amount” element”. You might call your new made-up language “StupidML”. Documents in your new made-up language would be StupidML, but they would also be XML, since StupidML is a subset of XML

More advanced stuff

RSS is a language for syndicating headlines, that is, for providing lists similar to RecentChanges. There’s actually a couple of incompatible RSS standards with different version numbers.

WebDAV is a protocol that extends HTTP to deal with remote editing of web resources. Standard HTTP had “PUT” and “POST” to let you write to web resources, but WebDAV adds more stuff to help with this sort of thing. If you’re writing to web resources, you probably want to use WebDAV, not just PUT. Intro article. Links. RFC 2518. IETF working group.

DeltaV is a protocol that extends HTTP to do versioning for web resources. I.e. “hey, show me what this web page looked like last tuesday”. Note that WebDAV is a prereq for DeltaV. Links. IETF working group. RFC3253 with Errata Applied.

LDAP (“lightweight directory access protocol”) is a database access protocol & query language. LDAP lets you query servers for information, like “give me the email addresses of everyone in the database who lives in Detroit and whose last name is Smith”. It also lets you change the information in the database. LDAP does authentication & permissions. LDAP is a replacement for an older protocol called X.500. LDAP isn’t really a web standard (it’s not over HTTP), but I included it anyway.

Atom is an emerging protocol for interaction with weblogs (i.e. for weblog authors to remotely post their stories, as well as other stuff).

DASL is a non-standardized future protocol that extends HTTP to allow submission of queries & searching in a standard way. Note that WebDAV is a prerequisite for DASL.

Web services specific stuff

Web services means that one program on your computer calls a subroutine in another program, and the other program is running on a computer in Los Angeles. Your computer passes arguments to the other computer via HTTP, and then the remote computer runs the subroutine over there, and then it returns the result to your computer via HTTP.

SOAP is a protocol for calling program subroutines remotely. It also specifies how to encode some data types (strings, integers, etc) in XML. For example, I want to call a calculator program in Los Angeles to add 2 + 2. I know the URL and the port and all that already. I tell SOAP, “call subroutine “add” at this URL, and pass it two integer arguments, “2” and “2””. SOAP passes on the information, the remote computer does the computation, and then SOAP tells me, “the result was “4””.

XML-RPC is an earlier protocol to do the same thing as SOAP. I think SOAP is the way to go nowadays.

WSDL is a language for describing the API of a web service. For example, a WSDL document might say, “Program ‘Calculator’ has four subroutines, ‘int add(int, int)’, ‘int subtract(int, int)’, ‘int multiply(int, int)’ and ‘real divide(int, int)’.

More advanced XML-specific stuff

XPath is a standard langugae for addressing information within XML documents. It allows you to refer to things like “the <title> element of this XML document”.

XQuery is a language for writing queries for information within XML documents. It’s like SQL for XML.

RDF (“resource description framework”) is a language for talking about properties of URIs. E.g. it says things like “the owner of http://microsoft.com is Microsoft Corporation” or “The sex of www.fake.name/Shanks/Bayle/TheOneWhoLivesInSanDiego is “male””.

XSLT is a language for defining a transformation to be applied to XML documents. For example, an XSLT transform might be used transform XML documents into HTML documents.

Some wiki-specific things

ModWiki is a module for RSS to define a sublanguage for talking about properties of Wiki Changes, such as “importance” (minor edit/major edit).

WikiXmlRpc? is a (non-standardized) API for automated, remote interaction with a wiki (you send the wiki commands like getPage, putPage, etc).

Semantic web stuff

RDF, the Resource Description Framework, is “a language for representing information about resources in the World Wide Web”. It can also be applied to describe information about other things. There are a couple of different formats for actually writing RDF down. The canonical one, RDF/XML, uses XML. Another one is N3 (Notation3), which is simpler to read and write. To learn more, check out O'Regan's article, Mazzocchi's article (pt II), or the W3C’s lengthly RDF primer.

Some things I don't know yet

I dunno exactly what JXTA is. Something about a specification for infrastructure for P2P stuff.

Perhaps you may read http://www.jxta.org/

Contributors: Bayle Shanks

Collection of References

Wiki developers: Oddmuse:References is what AlexSchroeder uses for his wiki development stuff.

The Protocol Info wiki looks like it might become a good place to discuss web standards and other protocols.

thanks, but it looks to me like it is focused on how a network admin can detect the usage of that protocol on their network – not a place to discuss where, why, and how the protocol should be used – BayleShanks

The PICA wiki looks like a good place to develop new web standards and protocols.




  • XML-RPC comes by default with every scripting language I know of. (No additional installs.)
  • XML-RPC is a lot easier.

I dunno, I suppose I could go to the work, and force the work of on my target audience, of installing SOAP. But what would I get?

And, at least in Python, it’s harder to build and send a SOAP message than an XML-RPC message.

In Perl, I thought they were just as easy.

Neither one is a standard library, so the user has to install a library either way. The library I use (SOAP::Lite) provides both SOAP and XML-RPC.

They both look about the same level of difficulty to use:

Perl SOAP client:

         use SOAP::Lite +autodispatch =>
           uri => 'http://www.soaplite.com/Temperatures',
           proxy => 'http://services.soaplite.com/temper.cgi';

         print f2c(32);

Perl SOAP CGI server:

         use SOAP::Transport::HTTP;
           -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Mod
           -> handle;

Perl XMLRPC CGI Client:

             use XMLRPC::Lite;
             print XMLRPC::Lite
                 -> proxy('http://betty.userland.com/RPC2')
                 -> call('examples.getStateStruct', {state1 => 12, state2 => 28}
                 -> result;

Perl XMLRPC CGI server:

             use XMLRPC::Transport::HTTP;

             my $server = XMLRPC::Transport::HTTP::CGI
               -> dispatch_to('methodName')
               -> handle

So, given that, the fact that SOAP was created after XML-RPC and tried to learn from its mistakes (whatever they were), and the fact that it seems more of a “standard”, I think SOAP is the way to go.

As for Python SOAP, I’ve never used it, but it looks simple enough (from http://interview-machine.com/soap/newdoc/html/node6.html and http://interview-machine.com/soap/newdoc/html/node5.html):

Python SOAP client:

from pythonsoap import soaprpc

client = soaprpc.RPCClient("http://localhost/example")

print client.echo("SPAM")

for number in range(1,10):
    print client.echo(number)

Python SOAP server module 1:

# file testsvc.py

def echo(object):
    return object

Python SOAP server module 2:

from pythonsoap import http,soaprpc
import testsvc

rpc = soaprpc.createRPCService(testsvc) # creates an RPC service
binding = http.ApacheBinding(rpc)

# the actual handler
def handler(req):

    return binding.request(req)

Is there hidden difficulty in using this sort of thing? Or it is that XML-RPC is a standard lib in Python, and SOAP isn’t (which I would say is Python’s fault in being behind; anyway, my philosophy is that using libraries is a great thing, as it keeps your code more concise and readable; in this age of modern packaging systems, I say use as many libraries as you can)?


Thank you for answering so clearly!

I see that I was looking at the wrong Python documentation; I was looking at documentation on how to send a SOAP message, not on how to do a SOAP RPC call. You are right; The SOAP call looks as simple as the XML-RPC call.

Still, it seems to me that most web communication systems right now are XML-RPC based.

And also: Python comes with xmlrpclib. You have to install SOAP as this additional thing.

I just did a little research, and found an article on the trade-offs between XML-RPC and SOAP. It is slanted towards XML-RPC; Something to factor into reading.

Again, thank you for the clear answer.

I think I still prefer XML-RPC to SOAP, but I understand the issues better now.

For a bit of design philosophy and short comparisons, check The Art of Unix Programming by Eric S. Raymond, chapter Application Protocol Metaformats. [1] It has a section called XML-RPC, SOAP, and Jabber, too. [2]

I’ve come to disagree that the purpose of RDF is to talk about things on the web, or URI’s in general. (Thread continued on ResourceDescriptionFramework.)

URI’s: I believe that a thing is a URI if it is a URN or a URL. I believe a thing that is a URI is either an URN or a URL. I don’t believe there are any other things it could be.

An URN is a generic word for something, without any particular designation of location. URL’s tell you how to find a particular instance of something. An URN is the name in the abstract. I wrote about this on Wikipedia.

I have difficulty understanding how URNs and URLs are different.

urn:isbn:0451450523 may sound like it’s talking about “The Last Unicorn” in the abstract (URN), without telling me where to find it (URL). “http://communitywiki.org/” may sound like it’s telling me how to find something, but without telling me what it is.

But is that really the case? If I have the ISBN, I know where to find a (first digital, then physical) duplicate by going through the library system. If I have an URL, I know where to find a digital duplicate by going through the IP-TCP-HTTP system. Does it really make sense to say that one is a locator, but the other is a generic name? I don’t think so.

It makes sense because the “how to find a physical/digital duplicate” system is not unique for the ISBN. I could go to my local library, or to a university, or potentially check dozens of online resources to find it. OTOH, there’s only one way to dereference a URL.

To put it another way, there may be many mappings from a URN to a URL, or there may be none.

I try to conceptualize this, but I keep hitting a barrier.


  • You go to a local library. You request a book by ISBN. They look up the nearest duplicate. The ship the nearest duplicate over.
  • You go on the Internet. You request an image from some server. But that server’s actually a load balancer. It forwards your request to the server with the most time available. That server sends a duplicate of the image to the middle server, and the middle server again duplicates the image for you.

And then I go: “Ah-Hah!”

“By URL, there’s a single authoritative point! The ISBN system doesn’t have a single authoritative point, and that’s why there’s a seperation between URL and URN!”

But then I think, Oh no, there actually is a sigle authoritative point.

Somewhere in the world is a big book, and in that book, is a mapping between all the ISBNs, and the actuall books numbered by them.

There is some single point of routing between ISBNs and duplicates of ISBNs.

But perhaps it’s because the single authoritative point is behind the duplicates, rather than in front of them that the split is warranted?

Or perhaps we should just say that “ISBN” means ISBN numbers. As in: the numbers themselves. They don’t actually mean a book.

That would make some sense, then.

Does this sound about right? If it’s true, then I need to fix the Wikipedia page.

I looked up Google:URI+URN+URL and, via this document, found RFC 2396.

Here’s what it said:

A URI can be further classified as a locator, a name, or both. The term “Uniform Resource Locator” (URL) refers to the subset of URI that identify resources via a representation of their primary access mechanism (e.g., their network “location”), rather than identifying the resource by name or by some other attribute(s) of that resource. The term “Uniform Resource Name” (URN) refers to the subset of URI that are required to remain globally unique and persistent even when the resource ceases to exist or becomes unavailable.

Here are my thoughts on ISBNs:

  • I think the ISBNs refer to the books, not the numbers themselves.
  • ISBNs are supposed to be globally unique and persistent (I assume…), so they are URNs
  • There might be a big book mapping ISBNs to books, but there is not a standard way for any computer connected to the internet to access that book and to resolve ISBNs. There might be non-standard ways (like using Amazon), but that’s different.
    • But if you think that ISBNs count as a location anyway, then you might say that they are both URNs and URLs.

Define external redirect: WikiXmlRpc

EditNearLinks: ModWiki CategoryWebTechnology