API Type Classifications

#1

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 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.
5 Likes
#2

Looks really good @dmorrow!

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)

Cheers,
Sven

3 Likes
#3

That’s a great initiative @dmorrow!

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.

Cheers,
David

1 Like
#4

Thanks @david2. There’s an item in the list called capability schema which is intended to cover app descriptors.

#5

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):

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.

2 Likes
#6

Thanks for your thoughts @LukaszWiatrak. I think I need to broaden my description of extension points to cover this.