Define how to communicate between Front-End and Back-End

[raaaahman]

In order for front-end and Back-end to be developed apart from each other, a contract between the two should be established before end.

This would then be a good idea then to document the endpoint routes before they are produced by the back-end and consumed by the front-end.

It would also be a good idea to define data schema that will be used as reference for both sides of development.

[raaaahman]

Discussed during August 3, 2021 Office Hours:

@raaaahman :

I am starting to question the JSON formatted data that will become the bridge between both frontend and backend.
If you look at my PR on extending the notification model, I am using some JSON files as examples for my unit tests: https://github.com/WordPress/wp-notify/blob/908016a0385e66846685b1f884b0682c35d37a90/tests/data/notification-title-image-link.json
If you look at the fields name, they match specific PHP classes names: this is made for easily parsing them back into PHP objects.
But my concern now, is that a change in any PHP class name would require changes in every front-end script that uses this data...
Whereas there is no use case were we need to unserialize notifications from JSON having been discussed at the moment.

Maybe the names should be the one we used in the data model discussion? And they won't change: #16

@raaaahman :

I'm not sure we should pass recipients data to the frontend. If the user is not targeted by the notification, it should not receive it in the first place...
... but maybe somebody would have a use for the recipients if building something on our REST API? Could this bring vulnerabilities if we just hand down some recipients data to anyone who asks?
Like a username or an e-mail?

@Sephsekla :

It’s certainly best for things like GDPR compliance to avoid exposing anything that might be considered personal, unless there’s a good reason. (modifié)
But then does it need to be anything more than just the id?

[aerych]

If you look at the fields name, they match specific PHP classes names: this is made for easily parsing them back into PHP objects.
But my concern now, is that a change in any PHP class name would require changes in every front-end script that uses this data...

It sounds like this approach could impact any client consuming the JSON data, not just front end scripts? I'm assuming that any REST endpoints supporting WP-Notify can be accessed by any REST client and I'm thinking specifically of the WordPress, WooCommerce, and Jetpack mobile apps.

[raaaahman]

To go along with my proposal in the data model discussion, here's a JSON schema describing the data to be expected (following the json-schema.org standard):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://wordpress.org/feature.notification.json",
  "title": "Notification",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a notification",
      "type": "integer"
    },
    "sender": {
      "description": "The sender who originated the notification",
      "type": "object",
      "properties": {
        "name": {
          "description": "The name that identifies the sender",
          "type": "string"
      },
      "timestamp": {
        "description": "Timestamp from when the notification was originated, in milliseconds from January 1, 1970.",
        "type": "integer",
      },
      "recipients": {
        "description": "A collection of recipients who should receive the message, contains WordPress users' id only. Any recipient from a notification channel other than WordPress REST API won't be displayed here",
        "type": "array",
        "items": {
          "type": "integer"
        },
      "message": {
        "description": "Message to display to the recipients",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "fieldName": {
              "description": "This name will identify the field template to use for displaying this data",
              "type": "string",
            },
            "fieldContent": {
              "description": "The content of the message field will be displayed according to the template that matches the fieldName property.",
              "type": "mixed"
            }
          }
        },
        "status": {
            "description": "Whether the notification is read or not",
            "type": "string"
         },
         "level": {
            "description": "The level of severity of the notification",
            "type": "string"
         },
  },
  "required": [ "id", "sender", "timestamp", "recipients", "message", "status", "level" ]
}

Or maybe we'd better extract sub-schemas for our object (message, recipients, sender), so we could keep a base schema that stays the same and allow ourselves to changes its parts. (For example, displaying a sender logo)

[EdithAllison]

Linked to query about testing in #15