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

[darael]

I'm basically in agreement. The API needs to support these things, but a lot of them are most obviously done as multiple calls bundled up by the client. Ideally someone would write an API wrapper library clients could use. The remainder of this comment is thus a breakdown of responses to what azurelunatic said.

In order, then:
Fast user switching is probably most easily done by having actions specific to a user supply a username and auth token with the call. In this way, the API isn't stateful, requiring explicit user switches, but identifies the appropriate user on a per-call basis. Think of the model used in OAuth. In fact, unless I heard objections, using OAuth itself sounds sensible.

Retrieving comment relationships seems like it should be done by having calls to fetch the following four things: IDs of top-level comments on a post, given a unique ID for the post. IDs of the parent of a comment, given that comment's ID and the ID of that post (this one's lower priority, actually). IDs of the children of a comment, given its ID and that of its originating post. Comments by ID and post-ID.

Likewise, retrieving posts with a given tag seems reasonable to do by two calls (get IDs for (the first/last x posts) with tag y (starting from the nth), then retrieve posts by ID).

"Apply a tag to an entry" is a wishlist function, because it can be implemented with "get the tags on this entry" followed by some client-side logic and then "set the tags on this entry equal to...". Still a significant convenience, but if all else failed it could go in the aforementioned client-side API wrapper library. For this reason, call it a second-major-iteration addition.

Security settings really need to have a full set of calls associated with them, which is something on which I'd want to consult with people before defining the API.

Getting the userpic for a comment or entry is, once again, something I would expect to be done as a series of actions: First, get an identifier for the userpic, then either getting a URL for said pic and fetching it, having a call that returns the raw image data, or using a client-side cached version.