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

Hi @remie . Your nudge to reply is well timed - we obtained internal approval yesterday and are able to share our altered approach today. :smiley:

First however I would like to attend to some of your previous comments.

our feedback is dead on arrival

Iā€™m hearing that you feel our RFC process is disingenuous, which is unfortunate. We have taken a considerable amount of time to evaluate the feedback we have received, evidenced by the substantial shifts in how we have looked to deliver a solution that works for Partners. Not only is this so, in this RFC we have also sought to provide additional insight and reasoning into the various constraints we are having to consider. I can confidently assert that to claim RFC feedback is dead on arrival is not correct. :slightly_smiling_face:

Cloudevents

yet another fad

I can assure you Cloudevents is not a fad. It is a specification with broad industry participation and adoption, and an open PR to move it to CNCF graduated status alongside other not-fads such as envoy, istio, kubernetes and prometheus. I am not aware of any competing specifications for defining common event metadata and extensions (if you know of alternatives please let us know!), and a reason Cloudevents is part of CNCF is to demonstrate a multi-vendor commitment to its ongoing maintenance.

Atlassian does have a ā€œnot invented hereā€ problem

As you point out I have not been at Atlassian for a long time, so Iā€™m unable to comment on this sorry. However I do bring experience and an awareness of the need for unambiguous interoperability standards when operating public APIs at scale and with broad reach. One reason we have considered Cloudevents is with an eye towards future interoperability needs. Another is because it is simply good practice to define and use standard for message headers - a recent AWS architecture blog post about implementing Webhooks references Cloudevents as a best practice, the use of which ā€œprovides an industry standard format and common payload structureā€¦ā€.

So as we look to be a step ahead of future problems I hope you will agree our use of standard specifications is not reinventing solutions in-house.

look beyond your nice little project working with this Shiny New Thing

We have a lot of respect for our Partners and their needs, and we hope participants in the RFC process will afford us a similar level of respect, with consideration of the various concerns and constraints we are having to balance at our end. Let me assure you we are not treating App Access Rules as some sort of vanity project to advance peoplesā€™ careers. We select technologies and specifications for solutions based on whether they are fit for purpose, not for any personal promotion agenda.

Finally, let me restate that the only difference between cloudevents and not-cloudevents is the presence of two additional attributes in the event and a custom json media type, all of which you may ignore. Given you appear to agree there are no actual technical concerns with the use of Cloudevents I will draw a line under the Cloudevents aspect of the RFC. We have sought feedback and it has been received - thank you for your expression of Partnersā€™ desires for stability and consistency of our public APIs. We too appreciate these things. :slightly_smiling_face:


Now to the substantive matter of this replyā€¦

Web APIs

The additional details/use cases @remie and @danielwester and @lexek-92 recently provided have been very helpful, thank you all! One reason this reply is so delayed is because we have gone back and worked with Jira and Confluence to try and move our solution closer to what Partners have suggested.

Previously we proposed an architecture with a new centralised API, that necessarily uses ARIs in its contract;

Having taken on board feedback we instead propose the following;

In this architecture new API endpoints relevant to App Access Rules are provided directly from Jira and Confluence and the API shape is product-specific (i.e. determined by Jira and Confluence). The web API endpoints provided for apps running in an environment where App Access Rules could be in effect can now be summarised as follows.

Determine whether the app is subject to policy restrictions in a given installation context:

Jira

GET /rest/api/3/contentpolicy

{
    "anyContentBlocked": true
}

Confluence

GET /rest/api/3/contentpolicy

{
    "anyContentBlocked": true
}

Retrieve containers (Jira projects or Confluence spaces) and their associated content policy:

Jira

GET /rest/api/3/project/search?expand=contentpolicy

{
  "self": "https://your-domain.atlassian.net/rest/api/3/project/search?expand=contentpolicy&startAt=0&maxResults=2",
  "nextPage": "https://your-domain.atlassian.net/rest/api/3/project/search?expand=contentpolicy&startAt=2&maxResults=2",
  "maxResults": 2,
  "startAt": 0,
  "total": 7,
  "isLast": false,
  "values": [
    {
      "self": "https://your-domain.atlassian.net/rest/api/3/project/EX",
      "id": "10000",
      "key": "EX",
      "name": "Example",
      "contentpolicy": {
        "anyContentBlocked": true
      }
    },
    {
      "self": "https://your-domain.atlassian.net/rest/api/3/project/ABC",
      "id": "10001",
      "key": "ABC",
      "name": "Alphabetical",
      "contentpolicy": {
        "anyContentBlocked": false
      }
    }
  ]
}

Confluence

GET /rest/api/3/contentpolicy/space

{
  "results": [
    {
      "id": "string",
      "key": "string",
      "name": "string",
      "contentpolicy": {
        "anyContentBlocked": true
      }
      "_links": {
        "webui": "string"
      }
    }
  ],
  "_links": {
    "next": "string"
  }
}

Our understanding is that these changes will resolve the following concerns expressed by Partners;

  • Use of ARIs - these are no longer part of the API contract.
  • Use of GraphQL - the new API capabilities are provided via product RESTful APIs.
  • Performance - it is possible to retrieve in a single request both containers (i.e. Jira projects or Confluence spaces) and their associated content policy indicators, such as whether there is anyContentBlocked. While evaluating policy will always incur some compute overhead, we have removed the additional network hop.

OpenAPI contracts may be found in a separate reply - as to include them here causes the reply length to exceed limits.

Events

We are yet to confirm this (will take another day or two) but I would like to share already an event we propose to publish to help address the following use case;

in which app access is blocked after the user configured the project synchronisation, in which synchronisation will fail without any warning and we do not have any means to communicate this to the end-user

The proposed AppAccessToObjectsInContainerBlocked event will look similar to this:

{
  "specversion": "1.0",
  "type": "avi:ecosystem.app_policy:blocked:app_access_to_objects_in_container.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"
    },
    "blockedContainer": "12345"
  }
}

The purpose of this event is to allow apps to

  1. Store a record that a configuration change has occurred (useful in customer support scenarios)
  2. Update app configuration in light of the fact that background processes such as synchronisation will have been affected.

Conclusion

This RFC (and related earlier RFCs) has taken much longer to resolve than we had hoped. We know there will be improvements we can make to the process and will be taking this into consideration for future RFCs.

As noted at the start of this long reply we really do take notice of what our Partners have to say, and are greatly appreciative of the engagement we have had in this RFC. We hope you agree that even a long RFC process is still better than our delivering a solution as a fait accompli!

Thank you again, and we look forward to seeing some of you at Atlas camp. :slight_smile:

4 Likes