momijizukamori: Grey tabby cat with paws on keyboard and mouse. The text reads 'code cat is on the job', lolcats-style (CODE CAT)
Cocoa ([personal profile] momijizukamori) wrote in [site community profile] dw_dev2017-10-10 10:29 pm
Entry tags:

API wishlist?

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)
pauamma: Cartooney crab holding drink (Default)

[personal profile] pauamma 2017-10-11 04:20 am (UTC)(link)
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: (Default)

[personal profile] siderea 2017-10-11 05:25 am (UTC)(link)
*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?

(no subject)

[personal profile] siderea - 2017-10-12 06:25 (UTC) - Expand

(no subject)

[personal profile] siderea - 2017-10-12 06:39 (UTC) - Expand

(no subject)

[personal profile] siderea - 2017-10-12 06:42 (UTC) - Expand

(no subject)

[personal profile] siderea - 2017-10-12 07:11 (UTC) - Expand

(no subject)

[personal profile] siderea - 2017-10-13 19:00 (UTC) - Expand

(no subject)

[personal profile] siderea - 2017-10-13 19:08 (UTC) - Expand
ewx: (Default)

[personal profile] ewx 2017-10-11 07:37 am (UTC)(link)
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-)
brooksmoses: (Default)

[personal profile] brooksmoses 2017-10-12 10:00 am (UTC)(link)
FWIW, I'd want that for a "show me which of my friends' posts have new comments" functionality. Which goes with what [personal profile] siderea said above about enabling functionality that DW doesn't have.
kaisa: (Default)

[personal profile] kaisa 2017-10-11 07:38 am (UTC)(link)
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. :)
Edited 2017-10-11 08:11 (UTC)

(no subject)

[personal profile] kaisa - 2017-10-13 19:30 (UTC) - Expand

(no subject)

[personal profile] kaisa - 2017-10-14 07:58 (UTC) - Expand
ironymaiden: (in your computer)

[personal profile] ironymaiden 2017-10-11 02:08 pm (UTC)(link)
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.
siderea: (Default)

[personal profile] siderea 2017-10-12 06:47 am (UTC)(link)
I'd like to see access to the inbox, too. It would be great to be able to clients that backup and manage the inbox.

Also, I'm concerned that if the API manages to cause clients to happen, and people start DWing from the phones or desktop apps or whatever, and those don't support the inbox, it will become even more impossible to direct-message people, because those users will never see anything about it, unless they have turned on email notification (which apparently is not on by default?)

I don't just want the API to support the inbox, I kinda want inbox support to be mandatory for DW posting/reading clients. Because I'm afraid that otherwise clients will turn the inbox into dead.letter.

(no subject)

[personal profile] msilverstar - 2017-10-15 18:59 (UTC) - Expand
kaisa: (Default)

[personal profile] kaisa 2017-10-12 08:45 am (UTC)(link)
I completely forgot about inbox, because I don't use it. But yes, I think it would be good to have a call for number of new items in my inbox, because then that could also be set as a notification on a mobile device.

(no subject)

[personal profile] ironymaiden - 2017-10-13 14:18 (UTC) - Expand
green_knight: (Bruja Informatica)

[personal profile] green_knight 2017-10-12 09:02 am (UTC)(link)
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.)

(no subject)

[personal profile] green_knight - 2017-10-13 07:57 (UTC) - Expand
metahacker: And then a miracle occurs... (You need to be more explicit in step 2, here!)  (miracle)

[personal profile] metahacker 2017-10-12 09:06 pm (UTC)(link)
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: (Default)

[personal profile] andrewducker 2017-10-12 10:19 pm (UTC)(link)
/api/v1/journals/{username}/subscriptions - GET, list of subscription lists for journal (and POST to update them).
mdlbear: the positively imaginary half of a cubic mandelbrot set (Default)

[personal profile] mdlbear 2017-10-12 10:43 pm (UTC)(link)
(here via [personal profile] 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.
xevokitty: Cats - Ack / Surprise (Cats - Ack / Surprise)

[personal profile] xevokitty 2017-10-13 05:08 am (UTC)(link)
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.
green_knight: (Eeek!)

[personal profile] green_knight 2017-10-13 08:00 am (UTC)(link)
Yikes. (That must have been before my time, so over a decade ago, but that sounds like a spectacular failure.)

(no subject)

[personal profile] xevokitty - 2017-10-15 07:38 (UTC) - Expand

(no subject)

[personal profile] xevokitty - 2017-10-15 07:40 (UTC) - Expand

(no subject)

[personal profile] xevokitty - 2017-10-18 05:03 (UTC) - Expand
srukle: (Default)

[personal profile] srukle 2017-10-13 06:26 pm (UTC)(link)
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?
Edited (forogt a word) 2017-10-13 18:26 (UTC)

(no subject)

[personal profile] srukle - 2017-10-14 18:06 (UTC) - Expand

(no subject)

[personal profile] srukle - 2017-10-15 06:38 (UTC) - Expand

(no subject)

[personal profile] srukle - 2017-10-15 20:19 (UTC) - Expand
annathecrow: a sign of a disney-style cartoon character with a helmet and wings against a blue sky (Default)

[personal profile] annathecrow 2017-10-14 12:54 pm (UTC)(link)
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.

siderea: (Default)

[personal profile] siderea 2017-10-14 06:47 pm (UTC)(link)
/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.


(no subject)

[personal profile] darael - 2019-01-17 17:27 (UTC) - Expand
darael: Black lines on a white background.  A circle, with twenty-one straight lines connecting seven equally spaced points. (Default)

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

[personal profile] darael 2019-01-17 05:20 pm (UTC)(link)
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.