On clients and APIs

[darael]

Dreamwidth's APIs are poorly documented (people basically have to work off docs for old versions of LJ's APIs). They're also missing key features, like comment handling for more than backups.

I've been told there have been "some internal conversations about deprecating the XML-RPC API -- keeping it for backwards compatability, but moving to a much more modern second-gen API", but that nobody has had both the time and the inclination to work on designing such a thing.

Well, this is me, volunteering. To that end, I'm looking for input on what exactly such a new API needs to provide, and whether there's a preferred underlying technology to build on (exempli gratia, stick with XML-RPC? Change to SOAP? Use JSON? RESTful or not? et cetera). What I'm getting at here is that I'm entirely happy to take point, as it were, and to make decisions (especially where there's little or no consensus and someone has to make the call), draw up specs, write docs, and so forth, but the result is highly unlikely to be a really useful API unless I get input from more sources than my own experience and looks at the code.

At this stage, therefore, I want everything you, the reader, have to say on the subject. Use cases especially.

Go.

Comments

[damerell]

I realise this is going to be a bit moon-on-a-stick, but in my experience, it's a bad mistake to try and work out what an API needs to do; the API should make it straightforward to do anything one can do through the ordinary human-facing interface.

I say this because I've worked in large organisations where one group writes an API that happens to have this property, and another group, later, does something the first group never imagined. A formal requirements-listing process would have been entirely futile; the second group didn't know the API was being written, and didn't decide in advance what they wanted to do - they got the API and then thought about what they could do with it.

[darael]

I don't want to write an API to do specific things, but I do want use-cases for the simple reason that if I ask for them people are more likely to point out ones that would require something I've neglected to think of. As I'm also wanting to do this iteratively, so as to have something usable at the most basic level of functionality as soon as possible, these things also help me decide what goes in from the start and what should be deferred to the second or later iteration.

As for "anything one can do through the ordinary human interface", it should (in a final version) do both more and less than that. The ordinary human interface does a whole lot of post-processing that's better left to a client, so in that sense YAAPI should do less, and it doesn't provide direct ways to access certain things, bundling them into larger units, in which sense YAAPI should do more.