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

[azurelunatic]

I think one of the models that would happily build stuff using an API would be role players. So some things that they'd need in applications, and I'm not sure how all of this translates into things the API needs:

Fast login switching
Something that tolerates network latency -- when I'm in the subway and I have no signal, I want to be able to hit send on an action and have the app realize that there's no connection and queue it for later, and in context with the fast login switching, if I'm working as User A and then as User B when the train comes out of the tunnel, I don't want my queued actions for User A to accidentally be sent as the current logged in user (B) instead.
Easy retrieval of related comments: given sufficient information to identify a comment, what is its direct parent, direct children, and whole thread? (Bonus points for easy pagination of the whole thread, because some RP threads get hella long.)
With any given comment, have I replied to it yet? And under which identity?


Some other things which are currently painful through the web involve entry management, like re-doing tags.

Retrieve all entries with a given tag.
Apply a given tag to an entry.
Retrieve the current tags for an entry.
Retrieve the current security settings for an entry. (Must play well with custom settings, including multiple custom security groups.)
Apply these security settings to an entry.
Retrieving the userpic for a given entry.
Retrieving the userpic for a given comment.


*pauses a bit to catch breath* I hope this is a good starting point.

[denise]

I think a lot of those use cases you mention are things that someone would want to build a client to do, but are not necessarily use cases for an API in particular. Which is a very tiny and perhaps useless distinction (since obviously for a client to be able to do something, the API needs to have provisions for it) but I think is perhaps worth making at this point?

Braindump comment to follow shortly.

[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.