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

[pauamma]

Most obvious (to me) things missing are lack of anything for logging in or out, commenting, or retrieving a user's reading page entries.

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

[ewx]

This is excellent news.

My suggestion is: 'list of posts and comments that have been created, modified or deleted since <time>', where <time> is something that can be used to reliably avoid gaps; it might be a sequence number rather than an actual time. Could be multiple queries for different kinds of object, with the caveat that nobody wants to poll every entry in a journal to see if there are changes to comments.

Obviously what I'm interested in here is incremental journal backups l-)

[kaisa]

I once (years ago) considered writing a mobile app as a learning project for school to give me notifications of new posts, but realized that the api really should support a couple of functions first.

- Number of new entries on reading page since time x
- Number of new entries on subscription filter y since time x
- List of subscription filters for my account

Those would allow displaying the number of new posts on mobile's front screen easily and setting up which number should be displayed on the mobile app.

Using push notifications for that would be extra nice, but I know nothing about them, being a noob. :)

[ironymaiden]

Get inbox updates.
Track.

AKA as a user I'd like to get real push notifications for tracked items and be able to view new comments.

[green_knight]

My wishlist item is 'documentation', especially if you're changing major aspects of how the API works. (I looked into implementing the reading list/access list split for an open-source client a couple of years ago, and had to bow out because there wasn't enough API documentation support. Now that I'm a better developer, I'd like to get back to this - OpenLJ works great with DW otherwise.)

[metahacker]

This is a good starting point--a very data-driven API. Thanks for doing this! I also get some days like that, and should figure out if this could count.

A second level down might also be nice:
given (auth, user, tag), get a list of entries
given (auth, user, accesslist), get a list of entries.
given (auth, user, entry), get previous or next entries.
Auth here is the identity to query using, since the results of those matter based on who you are.

Some more queries I find myself doing manually that might be nice to have a simpler way to do:

1. Translating between date and entries, in both directions. (It's one-to-many, of course.) Even cooler would be "get entries between START and END", but that's fancier.
2. Something regarding polls. Probably the ability to map entry to poll ID, then querying by poll ID to get poll results/status. (I put a poll in almost every entry, but I am...not typical.)

[andrewducker]

/api/v1/journals/{username}/subscriptions - GET, list of subscription lists for journal (and POST to update them).

[mdlbear]

(here via siderea)

I may have missed it, but I don't see anything here for retrieving, posting, or editing comments.

Can't wait to get my hands on this. Also, thanks for pointing me at Swagger/OpenAPI -- that's really useful.

[gatheringrivers]

Not sure this was covered, and my geek-speek is kinda impaired lately with crap sleep.

My suggestion:
Force the API to recognize security levels (filters) on posts. As in, if there is no implementation of filter levels, the only posts the script/program can see are public ones.

Reason:
There was some hullabaloo a LONG time ago about one of the various third party LJ apps (I don't remember which one, it was at least a decade ago that I heard about this) being able to *completely* bypass post filters/security levels, allowing anyone using that particular app to see *any* post on a journal, regardless of whether the user was included on a filter for that post or not.

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

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

/api/v1/journals/{username}/entries/{id}

[darael]

I see that you've decided to use POST for entry-editing (presumably by way of wholesale replacement). Have you considered allowing PATCH, which is intended for the purpose? I realise you'd have to either figure out how to apply application/json-patch+json to some kind of JSON representation of an entry, or break consistency and use text/x-patch as input, but it might be worth it for small edits on large entries.