On 20 Apr 2012, at 12:01, Bob Walker wrote:
On Fri, 20 Apr 2012, Stephen Jolly wrote:
On 17 Apr 2012, at 23:50, Bob Walker wrote:
On Tue, 17 Apr 2012, Stephen Jolly wrote:
On 13 Apr 2012, at 10:01, Kake wrote:
Finally, I want to rub off some of the rough edges that I keep bumping up against, e.g. there is no reason for our search to be a POST - it should be a GET so people can actually link to search results. So if there is a particular small thing that's been bugging you, now is a good time to tell me.
Lack of an API. ;-) But that's not a "small thing".
what do you mean by api? lots of data is availale as rdf and json.
Is there a convenient way to find out what data is already available in explicitly machine-readable forms? I'd be happy to take a look and see if I can make some more specific suggestions.
pages with rdf will have links to it.
http://london.randomness.org.uk/wiki.cgi?Cafe_East,_SE16_7LH http://london.randomness.org.uk/wiki.cgi?id=Cafe_East%2C_SE16_7LH;format=rdf rgl doesnt link to the json but you just change the format. http://london.randomness.org.uk/wiki.cgi?id=Cafe_East%2C_SE16_7LH;format=jso... these 2 tickets are currently relevant. http://dev.openguides.org/ticket/290 and http://dev.openguides.org/ticket/289
kake has been adding better json to some of locale and cateogry pages. i think.
The JSON representations (which I was previously unaware of) look like a very useful step in the direction I was thinking of. To answer your original question, my ideal API would have all the features necessary to create independent user interfaces to an OpenGuide (a native mobile application, perhaps), or to incorporate queries to an OpenGuide into other websites. Readily-parsable, stable representations of the node pages is a big part of it, and similar representations of the global category and locale lists would also be useful. The other obvious and significant missing piece would be JSON (or similar) representations of search results - http://london.randomness.org.uk/search.cgi?action=search&search=fish;for... currently throws a 500, for example, which is arguably a bug all by itself... A standard way to update node contents and metadata would also be needed, although arguably the existing form submission system could be used. A JSON representation of the "recent changes" page would be an additional convenience, as would be one for the user preferences page.
A good API would also fulfil some non-functional requirements - primarily good design (simplicity, consistency, principle of least surprise, etc - eg adding ;format=json to a request should return a JSON representation wherever reasonable, and fail gracefully otherwise), and good documentation.
Is that helpful? Feel free to disagree with any or all of it. :-) At the end of the day, the difference between a web API and a website with machine-readable data representations isn't necessarily huge, particularly if the URL structure is already sane - it's more about thinking of the way that a developer would want to be able to interact with the server as well as thinking about how a user would want it to behave.
Oh, and a specific useful addition to the JSON representation of node content would be the image details (where available).
S