API Type Classifications

General
, , , , ,
7

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.
  • GraphQL: https://graphql.org/
  • 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.
  • REST: Representational state transfer - Wikipedia
  • 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.