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

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

[momijizukamori]

I will add those to the list! I'm not sure push notifs would be possible under this framework, because that requires the server to make outbound contact all the time, instead of waiting on requests, and I could see that getting expensive quickly, but the others are definitely possible.

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

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

Push notification helpers: Prowl (for iOS), and Notify My Android

[mek]

There are some stand-alone mobile apps which make it very easy to send arbitrary push notifications to a mobile device.

iOS: Prowl https://www.prowlapp.com/
Android: Notify My Android http://www.notifymyandroid.com/

Your code can make a single HTTP request from your server, and these applications (and their back-end-services) do all the rest. Using these services/apps, sending arbitrary push notifications becomes nearly a one-liner.

I don't have personal experience with Notify My Android, but I've used and integrated Prowl (iOS) into a few projects quickly and easily.

Each user who wants notification would have to install the (appropriate) app, and provide DW with their unique notification key, which they obtain from the app. Then DW servers make one quick, light HTTP request with the user's key in it, and poof, notification pops up.

Prowl lets you not only include the notification message, but also an optional URL that the user can click on to go right to the relevant page (e.g., to see a newly posted comment).

I'd be very happy to help out, including doing some prototyping.

UPDATE: turns out you can also just send an email to {apikey}@api.prowlapp.com, and the mobile device will get a push notification.