WITW Part III: RESTful Landmarks

Volume 8, Issue 28; 21 Feb 2005; last modified 08 Oct 2010

Keeping track of landmarks.

And gentlemen in England now a-bed
Shall think themselves accursed they were not here,
And hold their manhoods cheap whiles any speaks
That fought with us upon Saint Crispin's day.
William Shakespeare

Instead of working on WSDL, which would arguably have been more informative, I've done something fun instead. Registered users can now supply a collection of landmarks. These landmarks will be used (aggregated with other users') in displaying the set of landmarks that are “nearby” for each user.

What's more, I think I have a properly RESTful interface to the landmarks data.

The landmarks URI is http://norman.walsh.name/2005/02/witw/ami/landmarks. Note that this URI is in the authentication realm for registered users.

Performing an HTTP GET on the landmarks URI will return the landmark data for the authenticated user. The resulting data will be valid according to the landmarks schema.

Performing an HTTP POST on the landmarks URI will update the set of landmarks. The posted document must be valid according to the landmarks schema. The landmarks provided will be added to the existing collection. If one of the posted landmarks has the same name as an existing landmark, the existing landmark will be replaced by the posted one.

Performing an HTTP PUT on the landmarks URI will replace the set of landmarks. The replacement document must be valid according to the landmarks schema.

Clever Usability Tricks

I don't know if this is a clever trick or an awful hack, but if you GET the landmarks URI with a browser that accepts the application/xhtml+xml media type and understands client-side XSL stylesheets, the transformed result of the landmarks data will include a form. If you complete that form and submit it, you will effectively POST a single landmark to your collection.

That means that you don't need to figure out how to POST or PUT data to the landmarks URI in order to add some landmarks.

Comments

Hi Norman, I dont know if this is a problem of my browser or if you misscode the Umlauts in my landmarks. I see some wrongly appearing ö at http://norman.walsh.name/2005/02/witw/ami/landmarks and http://norman.walsh.name/2005/02/witw/is?userid=goern gives me an parse error right after I added the landmark.

—Posted by Christoph Görn on 22 Feb 2005 @ 11:55 UTC #

Great work, Norm!

However, I'd like to see the ami/now form provide my landmarks as choices. The whole reason I set up landmarks was so as not to have to specify exact long/lat when I move from New York City to Austerlitz or vice versa. (And I don't agree that there is no significant difference between is/johnwcowan and ami/now, because they produce different results when GOTTEN.)

This of course leads to a semantic issue: what does it mean to be "at" a landmark? The Empire State Building is certainly a landmark in NYC; does saying I'm there imply that I'm actually at that *building*, or merely that I'm (reasonably) close to the lat/long of the building?

The precision (and accuracy) of measurement may have something to do with the question. I entered the most precise lat/long figures for the ESB I could find (hopefully, just as accurate), namely to 8 significant figures, but you only display them to within .01 degree, which is about 1 km for latitude and (at my latitude) about half that much for longitude. My house and my workplace are certainly within a km of the ESB.

(BTW, I continue to be annoyed that you don't pre-transform blank lines to

before invoking TagSoup. I expect blank lines in plain text to "work".)

—Posted by John Cowan on 23 Feb 2005 @ 04:35 UTC #

Thanks, John.

I agree that the POST form should provide your landmarks as choices. That's the obvious thing to do now that per-userid landmarks exist. I'll be overhauling the way the per-user data is stored and updated and I'll fix that deficiency when I do that.

Reworking the API to be more RESTful, allowing PUT and POST to the isa/userid address, will mean figuring out how to tell the server to present the form instead of the pretty-printed data. One idea I have is to deal with it the way I deal with the landmark data. That is, make the form with a client-side stylesheet. Then I could serve two stylesheet pointers and let you pick the "form" stylesheet if you wanted to do updates. But that'd rely on user agents that supported both client-side XSL and stylesheet switching. Another idea is to add a parameter: isa/userid?form=1. Maybe I'll do both.

I'm not sure how to deal with the semantic issue of being "at" a landmark. I had in mind that saying you were at the Empire State Building meant you were in that building, but I'm not sure that's a practical use for landmark data. I suppose I could assert a definition for "reasonably close", say less than 2km, but I'm not sure that's a good idea.

With respect to the displayed accuracy of the latitude and longitude data, I was just trying to make the pages "look nice". The values you enter are preserved exactly as you entered them and used for location and proximity calculations (though the great-circle-distance algorithm that I'm using at the moment claims to have accuracy issues for points separated by less than about 5 degrees).

And finally, I completely agree about blank lines. I should look into that. I should also upgrade to a more recent TagSoup.

—Posted by Norman Walsh on 24 Feb 2005 @ 12:45 UTC #

Ok, John, I think I've improved the blank line handling.

Now blank lines become paragraph boundaries as long as your comment doesn't include any explicit <p> or <pre> elements.

If you put your own /<p/ markup in, then you have to put it all in.

Better? Good enough?

—Posted by Norman Walsh on 24 Feb 2005 @ 12:59 UTC #

Come to think of it, do per-user landmarks really make so much sense, at least on the use side? I might own the ESB in terms of who gets to modify the entry, but why should I own it in terms of being the only one who gets to say he is at/near it? Why not give me a choice of all currently defined landmarks to specify my location with?

Why not simply display both pretty-printed data and form simultaneously? Things like "view source to see the data" are pretty hacky.

On reflection, I think that the semantics of landmarks should be changed to "near", with "near" left undefined; you are near a landmark if, in your opinion, you are near enough.

I like the new approach to blank lines. Maybe I'll even make it a TagSoup feature. :-)

—Posted by John Cowan on 24 Feb 2005 @ 04:57 UTC #

Letting users choose from all landmarks, not just their own, is among my plans. I'm not sure I like the idea of displaying the form and the data, that's going to encourage folks to POST when they don't have accounts or when they aren't viewing their own data. I suppose I could provide a cookie and show you the form for your data automatically.

And yes, I think 'near' is the way to go.

Anyway, WSDL is out of the way, so I'll be hacking my way through an update over the next week or so.

—Posted by Norman Walsh on 25 Feb 2005 @ 12:44 UTC #