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).
- REST: https://en.wikipedia.org/wiki/Representational_state_transfer
- GraphQL: https://graphql.org/
- 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 adata-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.