[openstreetmap/openstreetmap-website] Proposal for Messaging API (Issue #4509)

[Milan Cvetkovic]

### Problem

There are already several issues related to OSM Messaging and the visibility of messages to the user base:

- [PR #4070](https://github.com/openstreetmap/openstreetmap-website/issues/4070) - cosmetic modification on how number of new messages is presented
- [Issue #3129](https://github.com/openstreetmap/openstreetmap-website/issues/3129) - (closed) Block function to individual users
- [Forum discussion](https://community.openstreetmap.org/t/about-making-osms-messaging-features-more-efficient/100050)

As a main form of communicating to users OSM uses email. In some scenarios, OSM website displays a message notification indicator. In other scenarios, i.e. changeset comments, notes and diary entries activities, OSM website only sends emails to subscribed users. In some cases, there are RSS feeds as well.

If user uses alternate applications to contribute to OSM, there is limited API support for querying information related to messages users would be interested in:

 - Querying user details shows the summary counters for direct messages. Some applications use this info to display a notification and redirect users to OSM web site to access their messages.
 - There is no support for reading, replying or modifying messages.
 - Extracting the changeset comments user is subscribed to has limited support. There are active PRs improving the support in this area: [PR #4359](https://github.com/openstreetmap/openstreetmap-website/pull/4359). As of now, there is indirect support through RSS feed.

### Description

## Proposal - Extend API v0.6 to include Messaging API

This is the proposal for OSM Messaging API addressing direct messaging only.

### Requirements

  - applications need to ask the user's permission to access the messages on OSM on their behalf. The existing OAuth2 authorization framework would support the authorization, however the messaging is not covered by existing scopes. We propose    to add 2 additional scopes, one for reading messages, and an additional scope for creating new messages and sending them.
  - Messaging API requires the client to be properly authorized by authenticated user.
    Only messages related to the authorizing user are accessible - the user must be either the recipient or the originator of the message.
  - To prevent bulk messaging, sending a message must be throttled, similar to how changeset submission is throttled.
  
This proposal assumes the existing data model for messages in OSM. A message is shared by the originator and recipient. The messages can be marked as read/unread or deleted by the user viewing them. OSM website displays the messages separately in "inbox" and "outbox".

In addition, the API provisions for paginating the list of messages. Message id is used for ordering since for any other fields, for example ordering by message timestamp, would require an additional index.

### Throttling Considerations

To prevent abuse, we would implement throttling in a similar manner to the existing implementation for API from [PR #4319](https://github.com/openstreetmap/openstreetmap-website/pull/4319) or extending it to apply to the messaging API as well.

### Client Transitioning

We plan to work on transitioning OSM web site to use the Messaging API instead of directly accessing the content of the database. This will improve the user's experience by adding the pagination to inbox and outbox view. It would also be subject to the throttling limitations imposed by the API.

As the first client of this API, this will give us a chance to learn about API usage ergonomics.

### API Summary

API would allow 3rd party applications to implement front-end for complete management of direct messages sent to or received by OSM users. The following functionality would be provided:

- List messages received by the logged in user, limit the count of messages, support pagination and filtering by read/unread messages only:

      GET /api/0.6/user/messages/inbox

- List messages sent by the logged in user, limit the count of messages, support pagination:

      GET /api/0.6/user/messages/outbox

- Retrieve the content of a specific message:

      GET /api/0.6/user/messages/#id

- Update the read status of a message

      POST /api/0.6/messages/#id

- Delete a message:

      DELETE /api/0.6/messages/#id

- Send a new message:

      POST /api/0.6/messages


### Screenshots

_No response_

-- 
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/4509
You are receiving this because you are subscribed to this thread.

Message ID: <openstreetmap/openstreetmap-website/issues/4509 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20240207/df8597f7/attachment.htm>