To support parity with Connect apps, Forge recently announced a preview for the Confluence Forge app properties API, which includes a new API group supporting PUT/DELETE of app properties. Curiously absent is a GET endpoint for reading an app’s own properties.
The announcement says that “retrieval of app properties will be made available through Display Conditions for Confluence”.
Does this imply that Atlassian will be making the GET endpoint available with delivery of that other feature set? Or that no GET endpoint will be made available at all, and that Atlassian expects that vendors will be limited to using app properties to trigger display conditions and nothing else?
Any clarification here would be appreciated. Thanks!
We meant that no GET endpoint will be made available (similar to Jira’s REST API), and that Atlassian Display Conditions will be the way to retrieve app properties moving forward.
App-level configuration which needs to be retrieved often should ideally be in KVS storage or similar.
Hope that helps - if you have a use case where you require a GET endpoint can you please share it with us here? Thanks!
Can you also share whether the Forge app property endpoints are restricted to being written only by the Forge back end? Or do they share the same architectural flaw from Connect in which the front end (and therefore an untrusted user) can also write to app properties? (And if it is truly mutable by the user, can this decision please be reconsidered? This is a long-standing source of grief for Connect developers.)
I admit that the whole concept of write-only app properties feels like a weird anti-pattern. Here is why I think GET access is necessary:
Connect apps have a single source of truth for things that can be controlled by display conditions: the app property itself.
The Forge equivalent now makes the display condition into the source of truth, but this “source of truth” is not actually accessible by the application (except indirectly in terms of controlling what is displayed to the user, of which the app may not be directly aware).
This paradigm unnecessarily complicates app migrations from Connect. Instead of being a 1:1 migration from Connect app properties APIs, all developers will now need to write additional code to store this data in two places and to try to figure out how to synchronize the two.
The suggestion to store the data in KVS but also in app properties creates a host of problems in real-world production environments:
The Connect app properties API already regularly fails with random HTTP 5xx errors. Example of error monitoring showing HTTP 5xx errors on the app properties API from one small production app:
In order to avoid support tickets being generated because of this split storage situation, the app now needs to ensure that the data is stored correctly in two places (and at least one of them is flaky). If the write succeeds to KVS but fails to the app property, we need to somehow sync from one to the other. However, apps cannot even perform a real “sync” operation because we cannot see what is stored in the app property to see if it is out-of-date…so we are supposed to just batch-copy data all data for all sites with a timed job? This generates unnecessary expense in terms of both compute and KVS operations.
If the write succeeds to the app property but fails to KVS, then the app’s concept of its current status will be out of sync with what the user sees.
In order to manage this reliably and handle retries, in addition to this timed sync job, do app developers truly need to push data-modifying requests onto an internal queue and handle the data motification asynchronously so that we can handle retries and broken APIs to ensure that the data is in sync? This seems like a whole lot of work (multiplied by thousands of app developers) for something that should be really simple.
As mentioned above, I believe the app properties should also only be writable by the back end. (If apps truly need to write from the front end, they can just pass the request to their own back end.)
Confluence already permits space-level data to be stored by the app, and in contrast to the app properties, it is actually readable. I do not understand why Atlassian is forcing a different paradigm for site-level data.
If Atlassian believes that KVS should be the place to store such information in a readable manner, why does this API even need to exist in the first place? Can you not delete the API and instead make display conditions work directly off the KVS? This is honestly where I thought Atlassian was going to go with this anyway (it avoids having multiple sources of truth) and I would be very happy to use that solution.
If Atlassian cannot key display conditions off KVS for whatever reason, could you pretty please support GET endpoint for app properties?
In short, I believe that the absence of “R” in “CRUD” for this API will generate a ton of extra work for app developers, and it is not at all clear why Atlassian would want to lock this down in the first place.
We need to be able to see in some fashion what’s stored. Not being able to read that just means that app properties are unusable and potentially even a security incident waiting to happen. I’m not even going to get into the iso/soc2 compliance of not being able to audit data trails.
Please Atlassian - please rethink this. We need to be able to see what’s in there from a developer perspective.
Or in another way - how should we interact with your support when we and the customers think that X is stored but Y is coming out?
I fully agree with @scott.dudley and @danielwester here. Without being able to read app properties we cannot implement a properly working configuration UI in our apps.
Using KVS as primary and app properties as write-only secondary store seems fragile and like a hack. Given that Forge app properties and corresponding display conditions are something being introduced right now, let’s please not force every vendor into coming up with such error-prone workarounds.
Hey @scott.dudley adding GET functionality for forge app properties has been prioritised and is being worked on at the moment. I hope to have some sort of changelog announcement update soon for you (by the end of September). Will also share it in this thread.
Can you also comment on whether the changes will also correct the Connect architectural bug in which app properties are writable by untrusted front-end code, even though they should not be?
I think there is strong support from the community for this fix, and if you agree, the time to correct it is probably now while the feature is still in preview (and not in need of deprecation delays).
Apps which truly need to update an app property from the front end could still do so through a resolver, so this change would not block any functionality, and making the fix now would resolve a bunch of long-standing security/permission issues.
Can you also comment on whether the changes will also correct the Connect architectural bug in which app properties are writable by untrusted front-end code, even though they should not be?
@scott.dudley Forge app properties can only be written and accessed by the forge app itself using the `asApp()` call. I’m assuming this addresses the issue you are talking about here. If not, could I have a link to the ticket/bug you are referring to?
Forge app properties can only be written and accessed by the forge app itself using the asApp() call.
That’s great—thank you!
Can you also clarify what expectations we should have regarding the lifecycle of data stored in app properties? For example, do these behave like Connect app properties in that they will be persisted across uninstallations and reinstallations of the same app?
