API wishlist?

[momijizukamori]

So my workplace gives us a chance twice a year to work on anything we want for a few days, work-related or otherwise, and I thought I'd use some of my time to actually get the new API into a state where we can make it live. With that in mind! What endpoints would you like to see implemented? We're making this Swagger/OpenAPI-compliant, so everything takes JSON as arguments and return JSON formatted data. Stuff already on the list to do or partially done:

/api/v1/users/{username} - GET, shows info about the user (specific info TBD; subset of profile, probably?)
/api/v1/users/{username}/icons - GET, lists icons
/api/v1/users/{username}/icons/{iconid} - GET, returns icon data
/api/v1/users/{username}/journals - GET, returns list of journals with write access.
-- for now, returns only user's primary journal
/api/v1/journals/{username}/accesslists - GET, list of access lists for journal
/api/v1/journals/{username}/tags - GET, list of tags for journal
/api/v1/journals/{username}/xpostaccounts - GET list of xpost accounts
/api/v1/moods - GET list of moods
/api/v1/commentsettings - GET list of allowed comment settings
/api/v1/journals/{username}/entries - POST new entry, GET list of recent entries
/api/v1/journals/{username}/entries/{id} - POST edit entry, GET specific entry
/api/v1/journals/{username}/files - POST new file
/api/v1/spec - GET, returns a description of the API

(Mark and D, as usual, get the final say - some stuff people want may end up being security/privacy risks in non-obvious ways)

Comments

[siderea]

*starts hyperventilating*

As it happens now's kinda bad for me – this is interrupting my procrastination of other things. What's your timeline for comments being useful? Can you give us a deadline for getting back to you?

[momijizukamori]

My big push is going to be end of this week/this weekend, but I doubt I'll get EVERYTHING done so - whenever you've got time?

Access to the accesslist membership lists?

[siderea]

Okay, I'm back.

You have:

/api/v1/journals/{username}/accesslists - GET, list of access lists for journal

How about allowing manipulation of accesslists by API? In parallel with your other URLs, we could have:

/api/v1/journals/{username}/accesslist/{accesslistid} - GET, list of members of access list; POST, save list of members of access list.

But honestly, I would feel better, as a developer, being able to add or subtract individual users from an accesslist, rather than having to overwrite the whole thing every time I made an edit. The latter seems like a recipe for really awful bugs.

Use cases: GET: being able to retreive a list of members means I can back up my access lists, something that is important to me, and actually super hard. I've also kicked around an idea of combining such a feature with OpenID, such that I could run a website where if users authenticate there with their DW OpenID, they can have access to things based on my access lists – basically API access to my accesslist memberships lets me use DW's ACLs elsewhere. So I could, for instance, set up sound or PDF or video sharing just for people on my access lists. POST: remote/client management of membership.

Need to think through how this will work with comms

[siderea]

We should probably think through how all this will work with communities, to make sure nothing is incompatible with them, later on when the API is extended to them.

I mean everything looks fine to me at the moment, but it's 2:21am local time.

[siderea]

/api/v1/journals/{username}/entries/defaults - GET, returns the key-value pairs of all the default settings for a journal's entries (i.e. security, commenting, screening, ?).

Use case: so posting clients can correctly apprise the user of what the default behavior will be when they hit the Post button.

[siderea]

I'd kind of like to be able to do the sorts of navigational things via the API one can do via the standard web interface: return a batch of entries all of the same:
• tag
• security level (including custom levels)
• year
• month
• day
in chronological or reverse chronological order.

(If it would be possible to intersections of any of {tag, security, date}, that would be grand.)

Usecase: that would be a step in the direction of being able to have an entry-management tool, that allows bulk changes to batches of entries, like "set all entries older than X to No Comments" and "set all entries tagged 'my sex life' to Private".

[siderea]

/api/v1/journals/{username}/files - POST new file

And can we have GET list of files?

(A way to back up files!!)

[siderea]

I want to acknowledge I'm dumping a lot out here, and want to apologize if I'm being overwhelming. I was taking that "wishlist" thing at its word.

As a general principle, I'm personally far more interested in the power of third-party apps (mobile, desktop, or even server) to provide functionality to DW that it doesn't have, rather than to provide alternative platforms for access that do what the website (or a subset of the website) already does. I think there's a tendency for APIs for web-based services to be designed to focus on the core functionality of the web user interface; but by opening up the non-core functionality, an API allows third parties to solve problems for the service and provide novel features.

Backup utilities is a classic example, and what with the Great Russian Migration from LJ earlier this year, I think it's on a lot of people's minds. There was no reasonable way to back up one's images from LJ, because the API didn't cover it.

Similarly, providing API access to images allows hypothetical client developers to do things like make phone clients that interoperate with cameras, to make it super easy to post photos to DW. That would probably be a popular feature – it could even make DW more competitive as a platform – but not so certain a thing that DW would want to invest in developing such a client. An API allows third parties to take a stab at it, and DW to benefit by it if they do.

[momijizukamori]

Heh, the reason I started working on the API was to be able to provide utilities for RPers (like generating a list of all your comment threads in a comm, or counting how many comments or entries you made in a month), so I definitely hear you on opening up stuff for other devs to implement non-core functionality like that.

And no worries about the amount of stuff! It may not all get done this push, but it's good info to have going forward.

[siderea]

♥!

So, I'll just add this, while asking for the moon:

/api/v1/journals/{username}/grants - GET returns the list of usernames that username (actually {journalname}) grants access to – and if {username} has that public on their profile, you don't have to be authenticated to the API to get it.

Because I think – not sure, but I've thought cursorily through this – that's the last technical obstacle between here and DW Phone Posts being a viable, commerical third-party service. Not that's I'm promising to start a DW collateral business in my non-existent spare time, but. Just sayin'.

(If there is an unemployed dev ops/sys admin/developer who always wanted her own business, and thinks this might be it, she should shoot me a DM.)

[siderea]

Oh, and! Speaking of asking for the moon:

It would be awesome – and way beyond the functionality of a mere API as presently being conceived – if DW had a settings page that allowed users to create API access keys that granted permissions to an arbitrary subset of DW functionality, so then they could hand the API access key over to a third party, to let that third party act as an agent, with less-than-full control of one's journal.

• A backup service could be allowed to read one's locked posts, but not one's grantors' locked posts, and have no write access at all.

• An automated posting service, e.g. IFTTT, could be allowed to post, but not read or comment at all.

• A design service could be allowed to change one's journal's style, without having any access to locked content, and no other write or read permissions.