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
pages with rdf will have links to it.
rgl doesnt link to the json but you just change the format.
these 2 tickets are currently relevant. http://dev.openguides.org/ticket/290
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 -
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
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).