RFC-29: App Access Rule - Revised followup to New Data Access APIs

General Request for Comments (RFC)
14

This reply is in response to ongoing expressions of concern about Cloudevents. In conjunction with the explanatory note about Cloudevents in this RFC I will explain by way of example show how the use of Cloudevents should be completely transparent to Partners, who should be able to work with plain json objects as usual.

Schema diff

If we were to ignore Cloudevents entirely (while still including event schema properties we feel are desirable), an example AppAccessToObjectsBlocked event would look like this;

{
  "type": "avi:ecosystem.app_policy:blocked:app_access_to_objects.v1",
  "id": "7a6796c0-746d-4504-92cd-819eca234306",
  "time": "2023-10-24T08:08:08Z",
  "data": {
    "site": { 
      "url": "https://site_name.atlassian.net"
    },
    "blockedObjects": [
      {"type": "page", "id": "12345"},
      {"type": "page", "id": "23456"},
      {"type": "page", "id": "34567"}
    ]
  }
}

If we then add whatever is necessary to align with Cloudevents, an example AppAccessToObjectsBlocked event (and what we propose in this RFC) then looks like this;

{
  "specversion": "1.0",
  "type": "avi:ecosystem.app_policy:blocked:app_access_to_objects.v1",
  "source": "com.atlassian/ecosystem.app_policy",
  "id": "7a6796c0-746d-4504-92cd-819eca234306",
  "time": "2023-10-24T08:08:08Z",
  "data": {
    "site": { 
      "url": "https://site_name.atlassian.net"
    },
    "blockedObjects": [
      {"type": "page", "id": "12345"},
      {"type": "page", "id": "23456"},
      {"type": "page", "id": "34567"}
    ]
  }
}

These two event schemas are clearly very similar.

The specific changes are;

  1. The http Content-Type header value changing from application/json to application/cloudevents+json.
  2. Addition of a specversion property - which may be ignored if not relevant to the event consumer.
  3. Addition of a source property - which may be ignored if not relevant to the event consumer.

We can now make the following observations;

  • The effective change to json schema made in order to align our event schema to the Cloudevents specification is the addition of two properties - which may be completely ignored.
  • If an app’s http request handler does not register a Cloudevents content type parser it will fallback to the json parser that will already be registered for Atlassian webhooks.
  • Every one of these schema changes are completely transparent to the app. An app can perform ordinary json parsing of the event payload, as it does today for all other Atlassian events.

Binary content mode

While we have withdrawn the proposed binary content mode, it seems this was misunderstood and so it may help to clear this up.

Cloudevents ‘Binary Content Mode’ simply means the event metadata and data are not carried together; metadata is carried via transport headers and data in the message payload.

For http webhooks this means the id, type, time properties are carried as http headers, and the data property is the http message body. It is not binary encoding, it is binary (two-pieces) transport. (As opposed to ‘Structured Content Mode’ which keeps event metadata and data together in the payload.)

Broader rollout

To be clear, we have not committed to evolving all existing event schema to align with Cloudevents, and there is no intent to do so. While consistency of event metadata in schema would be wonderful we believe mandating this would be an enormously disruptive change.