Messaging API proposal

From OpenStreetMap Wiki
Jump to navigation Jump to search

This is the proposal for API specification for User messaging. The purpose of the API is to allow applications to implement front-end for messages received and set by OSM users.

Main Github issue for comments is at https://github.com/openstreetmap/openstreetmap-website/issues/4509.

Requirements

  • Applications need to ask 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, and additional scope for writing messages.
  • Messaging API requires the client to be properly authorized by authenticated user. Only messages related to the authorizing user are accessible - the user needs to be either the recipient or the originator of the message.
  • To prevent bulk messaging, sending a message needs to 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.

Access Rights

Two additional access rights will be added to support message manipulation:

message_consume
Allow actions on messages belonging to the user: read messages, update read/unread status of the message, delete message.
message_send
Compose and send messages to other users.

Throttling Considerations

To prevent mass messaging, we will implement throttling in a similar manner as the existing implementation for API from PR #4319, or extending it to apply to the messaging API as well.

Client Transitioning

We plan to work on transitioning OSM website 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 Specification

List messages for logged in user

List the messages' metadata in one of the two mailboxes for logged in user.

Note

The body of the message is not part of the response.

The output format can be specified by appending .json to the URL path. 

GET /api/0.6/user/messages/inbox
GET /api/0.6/user/messages/outbox

Parameters

limit
Optional. Maximum number of messages in the output. Specifies the maximum number of messages returned in the result. If not specified, default value is used.
order=[newest|oldest]
Optional. Messages are ordered by id in specified order. newest is used if not specified.
from_id
Optional, The id of the first element in the returned list.

Required permissions

message_consume

XML Response

  <?xml version="1.0" encoding="UTF-8"?>
  <osm version="0.6"
       generator="OpenStreetMap server"
       copyright="OpenStreetMap and contributors"
       attribution="http://www.openstreetmap.org/copyright"
       license="http://opendatacommons.org/licenses/odbl/1-0/">
    <messages>
        <message id="7777"
                 from_user_id="22222"
                 to_user_id="3333"
                 sent_on="2019-06-15T08:26:04Z"
                 message_read="true"
                 from_user_visible="true"
                 to_user_visible="false"
                 body_format="text">
            <title>Message title</title>
        </message>
    ...
    </messages>
  </osm>

JSON Response

  {
    "version": "0.6",
    "generator": "OpenStreetMap server",
    "copyright": "OpenStreetMap and contributors",
    "attribution": "http://www.openstreetmap.org/copyright",
    "license": "http://opendatacommons.org/licenses/odbl/1-0/",
    "messages": [
      {
        "id": 7777,
        "from_user_id": 22222,
        "to_user_id": 3333,
        "title": "Message title",
        "sent_on": "2019-06-15T08:26:04Z",
        "message_read": true,
        "from_user_visible": true,
        "to_user_visible": false,
        "body_format": "text"
      },
      ...
    ]
  }

Error Codes

HTTP status code 403 (Forbidden)
insufficient authorization
HTTP status code 400 (Bad Request)
when parameters are conflicting, i.e. both min_id and max_id are specified.

GET content and details of a message for logged in user

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

Parameters

id
Required. The id of the message to retrieve. Must be a message either sent from or sent to the user.

Required permissions

message_consume

XML Response

Full content and metadata of the updated message in XML or JSON format. 

  <?xml version="1.0" encoding="UTF-8"?>
  <osm version="0.6"
       generator="OpenStreetMap server"
       copyright="OpenStreetMap and contributors"
       attribution="http://www.openstreetmap.org/copyright"
       license="http://opendatacommons.org/licenses/odbl/1-0/">
    <message id="7777"
             from_user_id="22222"
             to_user_id="3333"
             sent_on="2019-06-15T08:26:04Z"
             message_read="true"
             from_user_visible="true"
             to_user_visible="false"
             body_format="text">
        <title>Message title</title>
        <body>The body of th message</body>
    </message>
  </osm>

JSON Response

Full content and metadata of the updated message in XML or JSON format. 

  {
    "version": "0.6",
    "generator": "OpenStreetMap server",
    "copyright": "OpenStreetMap and contributors",
    "attribution": "http://www.openstreetmap.org/copyright",
    "license": "http://opendatacommons.org/licenses/odbl/1-0/",
    "message": {
      "id": 7777,
      "from_user_id": 22222,
      "to_user_id": 3333,
      "title": "Message title",
      "sent_on": "2019-06-15T08:26:04Z",
      "message_read": true,
      "from_user_visible": true,
      "to_user_visible": false,
      "body_format": "text",
      "body": "The body of th message"
    }
  }

Error Codes

HTTP status code 403 (Forbidden)
Authorizing user is neither recipient nor originator of the message.
HTTP status code 404 (Not Found)
When the message does not exist.

Update read status of a message

Updates the status of a message for logged in user - recipient only. 

POST /api/0.6/messages/#id

Parameters

id
The id of the message to modufy. Must be a message either sent from logged in user or sent to logged in user.
message_consume
Boolean representing if user has read the message.

Response

Full content and metadata of the updated message in XML or JSON format.

Error Codes

HTTP status code 400 (Bad request)
when message_read parameter is missing or has invalid value.
HTTP status code 403 (Forbidden)
Authorizing user is not the recipient of the message.
HTTP status code 404 (Not Found)
When the message does not exist.

Example

POST https://www.openstreetmap.org/api/0.6/messages/2222?message_read=true

Delete a message

Deletes a message for logged in user, by marking it no longer visible. 

DELETE /api/0.6/messages/#id

Parameters

id
The id of the message to delete. Must be a message either sent by logged in user or sent to logged in user.

Required permissions

message_consume

Response

Full content and metadata of the updated message in XML or JSON format.

Error Codes

HTTP status code 403 (Forbidden)
Authorizing user is not the recipient of the message.
HTTP status code 404 (Not Found)
When the message does not exist.

Send a new message to a recipient from authenticated user

POST /api/0.6/messages

Parameters

recipient_id
Recipient user ID. Specify either recipient or recipient_id.
recipient
Recipient's display name. Specify either recipient or recipient_id.
title
The title (subject) of the message.
body
Full content and metadata of the updated message in XML or JSON format.
body_format (optional)
Format of the body message. Can be either text, markdown or html.

If not specified, markdown is assumed.

Required permissions

message_send

Response

The content of the new message in XML or JSON format

Error Codes

HTTP status code 403 (Forbidden)
insufficient authorization
HTTP status code 427 (Too Many Requests)
when throttling was applied
Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Messaging_API_proposal&oldid=2682788"