Greetings, authors of blog-posting desktop clients! This post is for you!

Actually, this post is about you. I’ve spent the past four hours trying to implement Atom Publishing Protocol. Actually, it’s been days longer than that as I’ve been implementing and re-implementing accoring to the various documentation I’ve found online, but I’ve spent the past four hours just trying to get Ecto to work with my APP server code, and now I’m flat-out angry. It’s not just Ecto, and I’m not sure that I should only blame the Atom architects either, so let me explain my issues.

I’m trying to implement a lot of the Atom Publishing Protocol as a server. I want to be able to list blog entries, update them, and create new ones. I have written my Atom implementation to the most recent spec, and when I access the entrypoints using raw Telnet and HTTP headers over port 80, I get the appropriate responses back from my server according to the spec.

This seems great, but this is not the end of the battle – The so-called “Atom clients” I’ve been able to find just don’t seem to support the spec.

Let me start with some basic issues. Whether these are borne from problems with the spec itself or from the clients that attempt to implement it, we’ll have to figure out somehow.

Atom has this thing called introspection that allows you to essentially ask a server what Atom information it can provide, and where you can go to get it. It’s a pretty simple XML format, much simpler than the Atom collection/entry format itself, but it gets the job done.

The problem? Everyone seems to want it to look a different way. Maybe there isn’t an final version of this structure, but it seems like for something so simple, you could have settled on something by now.

Be that as it may, there are some more official-looking introspection format documents that seem to agree, so I’ve used those. They’re dated recently, and actually appear to me to work better than prior versions I’ve found. For example, Six Apart’s Atom introspection format looks like junk.

Ok, so say we have this introspection document at all. Your client tool needs to use it. If your software asks for an Atom endpoint, you need to be asking for the introspection URL. I know that it’s a big word, but let’s eliminate that confusion right now, and make people learn it.

Either that, or you need to accept the collection (feed) URL and the introspection URL as input. But be aware: Some sites will have more than one collection stored, and your users may want access to all of them, so you should probably get the whole list all at once, don’t you think? Use the introspection URL for this. It’s handy.

RSD. Ok, if you’re going to need Really Simple Discovery, then the API Link needs to point to, yes, the introspection URL! But this is just a nitpicky point compared to the one I will make next.

I know you’re trying to make it easy by allowing your users to select the tool (blogging software) they are using in order to select the most appropriate API. I applaud your effort to make it easy on your users. But here’s the thing…

I want Atom support. I do not want “Blogger” support, even if Blogger uses Atom. Why? Because for some reason, my Atom is not exactly like you expect Blogger’s Atom to be (for example, it’s not on Blogger’s server), and even though it works exactly like it, you’re not able to read it for some reason.

Ok, let’s just skip to the fundamental problems here, because I’m sure you don’t want to hear me rant about any tool in specific.

What I’ve been doing: I’ve essentially got a packet sniffer watching the requests that your client is making to my server in an attempt to figure out how I can appease it. Seriously, I’m that desperate as to have stooped to this kludgey level. That only tells me part of the picture, though.

The packet sniffing tells me where you’re looking, but not what you’re looking for. So if you require me to enter the Atom collection URL as an endpoint, but I enter the introspection URL, I see the request, but you fail to understand it. On the off chance you accept the introspection URL and that’s what I provide, then I should see you make some additional requests as you read the introspection document.

But I’m tired of trying to figure it all out.

I keep thinking that if you were following the spec to the letter, then I could just write my code to conform to the spec and it would all “just work”. But so far, I’ve been completely unable to point to any Atom client and say, “Here is a reference client. If I do something to my code and it can’t be read by this client, then it’s my APP implementation that’s broken, not the clients.”

Since nobody can seem to figure out how they want to get me to input the Atom URL (introspection? collection? entry? RSD?), I’m at a loss when trying to build a new APP server.

Here’s what I would like to happen: Please publish samples of the formats that you read. Please describe the URL that you accept in your configuration, and what type of document it should point to. If you are using RSD, please describe what the API should say to point to an Atom introspection URL, or the colletion URL, and whether you support one or both. Please list the extensions to the base Atom format that you accept and how well you handle them.

The “draft” tag is another good example of practicality being thrown out for academics. It’s not very clearly defined what an APP server should do with this tag. But most clients (and it’s odd that this is so common when the basic entrypoint URLs are so different between clients) use true or false as values in the draft tag. If you were posting to WordPress, the draft tag is completely insufficient. WordPress does not have only two states. Why are you even using this tag? Are you even using this tag?

At this point, I just want to get things to work, and I would like things to work with the API that I’m writing to conform with the RFC. I know it’s still changing, but it’s not changing so much that the tools should fail too badly between versions.

This is the same madness that went on with XMLRPC and the original Blogger API/Metaweblog API, etc. You shouldn’t treat Atom this same way. Atom is not XMLRPC. You shouldn’t need to force users to select the software they are posting to in order to anticipate what their feeds will contain. The Atom feed and entry document formats are fairly flexible in that respect. Embrace the future.

Wanna talk about it? Maybe I’ve got something wrong here. Enlighten me. Please.