I’ve recently been thinking about the various types of APIs that apps are dependent on. In this context, I’m defining API as simply a supported contract between apps and a product, platform, framework or library.
My intention is to be able to share a guide internally within Atlassian to improve the awareness of all the different ways an app can be dependent on our services. This would be used in our process documentation, etc.
Below are the types of APIs that I’ve identified so far. I’d be interested in hearing from you regarding any gaps, etc. I should point out that I’m focussing on cloud technologies that we either are using or are likely to use.
Authentication: This includes the authentication of API tokens and authentication flow aspects such as callback invocations and the presentation of consent screens.
Authorization: Any authorization processing to determine whether app operations are allowed (either inbound or outbound).
Webhook: Event notifications from a product to an app.
JavaScript APIs: JavaScript APIs can be exposed to app iframes using a combination of JavaScript libraries consumed by the app and PostMessage communication.
Context parameters: Atlassian Connect supports the notion of context parameters in iframe URLs.
Conditions: Atlassian Connect supports the notion of conditions to specify conditions under which an element is active.
iframe options: Similar to iframe parameters, Atlassian Connect also supports certain options to be specified by an app either using a special div element or by passing a data-options parameter when loading all.js.
Product URI: Some apps may be dependent on product URIs. For example, deep linking into products such as displaying a specific app project administration panel or locations where attachments can be retrieved from.
Extension points: Extension point locations control where app functionality such as web panels and applinks may be exposed within a product UI.
Capability schema: Schemas of various types of schemas that describe the capabilities of an app such as Connect descriptors and Forge manifests.
Library: Library APIs exist in the form of working code made available to an app.
Eventual consistency SLA: Some capabilities may rely on SLA semantics that an app may be dependent on in order to provide an acceptable user experience. For example, a user triggered operation may result in the indexing of content that a related app operation is dependent on which the user would expect to be available immediately or at least within some small period of time.
Not sure if this fits 100% what you’re going for here, but maybe storage would deserve it’s own point on your list? (E.g. app/entity/user properties and forge storage)
Maybe the app descriptor could be added to that list? It looks like some teams are forgetting about it. For example, the JCMA decided to force apps to dynamically register webhooks, which is a real pain (because you can’t do it immediately after receiving the /installed webhook) instead of just adding the webhook to the app descriptor, which would have been so much simpler.
I’m not sure how to categorize it in terms of the API, but it would be great to increase awareness of existence of custom content type, to make it first class citizen, with integration level on par with built-in types when it comes to integration with Confluence features.
Here are examples of features that work fine only for built-in content types (pages, blogs etc.) that are not supported for custom content (noticed by me or already causing inconvenience for my customers):
Custom content activity is not displayed in home page: in activity feed, in the list of recently visited/worked on items etc.,
Custom content activity is not displayed in user profile (‘worked on’ section),
Searching custom content in advanced search requires “type” be explicitly selected (doesn’t need to for built-in types), which is inconvenient and easily missed by customers,
Some of these features were previously working fine for custom content (like seeing recently added content on activity feed). I hope increasing awareness that custom content exists and is very important integration point for app developers will help to address issues above and reduce risk of regression - to not forget about custom content type e.g. when creating/rewriting some features or UI.
Here’s an update of the types of APIs that I’ve been maintaining since I initially started this topic:
App runtime: A problem relating to the execution of or interaction with a runtime that an app executes in. Forge functions is the only current app runtime.
Authentication: This includes the authentication of API tokens and authentication flow aspects such as callback invocations and the presentation of consent screens.
Authorization: Any authorization processing to determine whether app operations are allowed (either inbound or outbound).
Cardinality: Systems typically operate in the context of entities and events with certain ranges of cardinalities. Significant changes to cardinalities (e.g. 0 → n, n → 100n) can impact apps.
Conditions: Atlassian Connect supports the notion of conditions to specify conditions under which an element is active.
Context parameters: Atlassian Connect supports the notion of context parameters in iframe URLs.
Eventual consistency SLA: Some capabilities may rely on SLA semantics that an app may be dependent on in order to provide an acceptable user experience. For example, a user triggered operation may result in the indexing of content that a related app operation is dependent on which the user would expect to be available immediately or at least within some small period of time.
Extension point: An extension point extends the behaviour of a product or platform. Some extension points such as web items and web panels extend a products’ user interface whilst others do not. An example of a non-ui extension point is the ability to introduce custom content types.
Host Bridge: JavaScript APIs can be exposed to app iframes using a combination of JavaScript libraries consumed by the app and PostMessage communication.
iframe options: Similar to iframe parameters, Atlassian Connect also supports certain options to be specified by an app either using a special div element or by passing a data-options parameter when loading all.js.
Library: Library APIs exist in the form of working code made available to an app. Examples include @forge/api and atlassian-jwt node library.
Product URI scheme: Some apps may be dependent on product URI schemes. For example (a) deep linking into products such as displaying a specific app project administration panel, and (b) locations where attachments can be retrieved from.
Product and service hosting: Aspects about the way a product or service is hosted can impact apps. Examples include: (a) IP address ranges if communicated such as in this page and this resource.
Schema: Schemas that describe capabilities or formats such as (a) Connect Descriptor, (b) Forge manifest, and (c) Atlassian Document Format.
Terminology: Key terms relating to products, platforms and services need to be used consistently by apps. For example, the branding change of Jira project types.
Webhook: Event notifications from a product to an app. The API should identify the types of events, the payload schema of each event and expected responses from the consumer.