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

[green_knight]

Yikes. (That must have been before my time, so over a decade ago, but that sounds like a spectacular failure.)

[momijizukamori]

Thanks! I'm definitely guilty of just being like 'it does a thing!' because I've usually been neck-deep in code for hours at that point

[momijizukamori]

Yikes is right, that's a disaster. I'm pretty sure the code checks that (a bunch on the entry stuff is already developed) but yeah, robust testing necessary for sure.

[momijizukamori]

Those options are definitely possible! Though as I mentioned in another comment, I think push notifs may be too computationally expensive - that's a call for Mark to make

[momijizukamori]

You didn't want! The list wasn't intended to be complete, just 'what's happening first' - about half of it already has working code in dev.

[momijizukamori]

Definitely doable!

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

[ironymaiden]

Understood. I would happily pay for push notifications.

[casimirian]

Woah, so many comments.

This is great news, since some code I used in the past no longer seems to work for dw-free.

Thank you for taking this initiative. I wish you the best of luck!

Where will you make the code available?

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

[kaisa]

I guess it would depend on how many users are using the app and how often they are set to poll the numbers (how real-time the users want it), and how often the numbers change.. If you have a relatively rarely changing numbers, then polling them often would cause more load than pushing them. Also it might be a good idea to consider that there will probably be clients out there who (somewhat understandably) want to poll way too often to keep the notifications closer to real time. Real time does not matter to me personally, I don't know if it matters to other people.

[momijizukamori]

Hmm, true! I think push notifications may be out of my skill set, honestly, but I will definitely investigate.

[momijizukamori]

So the code will be part of the core DW repositories - If you mean more documentation stuff, you can see a sample of what gets generated here: http://www.momiji.hack.dreamwidth.net/api/v1/spec - which can be fed into something to generate a nice webpage view of it all pretty easily

[kaisa]

Investigation is good, and if it turns out that there's a need for this, then just recognizing that the need exists and writing it down is also a step forward.

[annathecrow]

Ohhh, that looks good. I do have some wishlist points:

some specific params for GET /api/v1/journals/{username}/entries:
- number of entries to fetch
- offset (so it's possible to get entries in batches)
- from & to timestamps (to get entries from a specific timeframe)
- fetch posts by tag

/api/v1/comments/{post_id} - GET comments on a post, with these params:
- number of comments to fetch
- offset
- from & to timestamps


Generally, I'm hoping for more "frontend" type of endpoints that would make the public data available for automatization/processing - i.e. backups, import/export. The old LJ API is geared toward content-generating apps, I'd love something more akin to Tumblr's API.

[casimirian]

Thanks, Momiji. I added this as a bookmark and will investigate while I'm not studying. I sincerely appreciate the work you're doing!

[siderea]

/api/v1/comments/{post_id} - GET comments on a post, with these params:
- number of comments to fetch
- offset
- from & to timestamps

Oooh, also a param for fetching just unscreened comments.

[momijizukamori]

You're welcome! Just a forewarning, that link is on my dev environment so it may randomly be offline as I work out bugs in my code.

[casimirian]

Heh. I've noticed. :) Np.

[gatheringrivers]

It was! Those who knew about it sometimes set up "secret journals" with only trusted people having access/knowing the address.

[gatheringrivers]

Please make sure that's enforced on the side of DW servers rather than the client. :)

With everything in the news, I'm sure people will appreciate feeling more like private/filtered entries will actually STAY that way regardless of how people access the journal.

[momijizukamori]

Oh, absolutely. My day job is in web application security, and while security and privacy are not quite the same thing, there's a lot of overlap in ideas and mindset :) Plus I'm working exclusively on the server-side right now anyway!

[momijizukamori]

I was poking around for some other stuff and realized I'd actually installed a nicer UI at some point for the API. http://www.momiji.hack.dreamwidth.net/api_ui/#

[momijizukamori]

Got it!