Exposure Perspectives
⏩ The technical requirements of this are described in the specification section on perspectives.
Overview
An application or service can be described both from a static or a dynamic perspective. The configuration endpoint can point to different ORD documents that represent the information from the different perspectives.
Static Perspective
The static system-version
perspective describes how an application or services looks like in general at design-time.
This perspective is especially useful for customers, who haven't purchased a product yet and need to understand what technical capabilities they would get.
It also helps to understand the common baseline of what all systems of the same type provide and how it changes over time.
In ORD, we describe this with perspective
: system-version
, to hint at the fact that the static metadata is usually version dependent.
Static metadata is known at design-time or deploy-time, when a new version of an application or service is developed or provisioned.
For cloud software with continuous delivery, the version may not be explicit or of interest to the consumer, a fallback to a "latest" version may be needed.
But consider that also cloud software that is going through phased deployments therefore can have multiple versions active at the same time.
The static perspective describes the shared metadata of all system instances (tenants) of the same system version. Either the metadata is always the same or it explicitly ignores the tenant-specific extensibility, configuration and any feature toggles - describing what's generic and shared. The advantage of static metadata is that is always available, there is no need to first provision tenants to get it. It is also a good integration contract for everything that is meant to work potentially with any tenant.
At SAP, we have the SAP Business Accelerator Hub that documents the static perspective.
Dynamic Perspective
The dynamic perspective describes an application or service how it really looks like, at run-time. This is more precise than the static perspective, because it can reflect configuration, customization and extensions of the system instance (tenant).
In ORD, we describe this with perspective
: system-instance
.
The system-instance
perspective is the correct choice, when the resource description or its metadata is actually different between system instances of the same system version.
When used, the perspective completely describes the running system instance as it is.
It is not a "diff" on the static perspective, for this we may consider introducing a specialized system-instance-delta
perspective as optimization later.
Some examples when metadata can be dynamic:
- APIs or Events can be activated and deactivated per system instance / tenant.
- APIs or Events interfaces can be extended, e.g. through field extensibility.
- New resources can be created by the user of the application at run-time (typical situation for frameworks, platforms and extensible applications).
- Endpoint URLs may be dynamic
At SAP, the run-time discovery of dynamic metadata (system-installation) is handled by the Unified Customer Landscape in BTP.
System Independent Perspective
Some ORD information like Taxonomies, Products and Vendors are not dependent on systems and can use the system-independent
perspective.
They can be considered global, static content that can be shared by multiple systems.
Such content is of a "singleton" quality for the whole ORD aggregator and SHOULD not be republished by the individual systems.
How Perspectives relate to each other
The dynamic perspective is a more precise description of the system instance than the static perspective, as it can contain its customizations. If no dynamic perspective has been published for a system instance, the static perspective can be used as the fallback. The system
This is depicted in the following diagram:
The system-instance
perspective is the most specific, because a consumer could ask how a particular system instance / tenant really looks like. If there is system-instance metadata for it, we can return it directly.
If we don't have it, we need to fall back to the system-version
layer and instead return the metadata for the version of the system instance.
If we don't know the version of a system, we can introduce a "virtual" system-type
perspective that doesn't have to be explicitly published.
The aggregator can treat the latest system-version
as the system-type
perspective and return it to represent the system type overall.
A consumer can legitimately be interested in all three levels, but he needs to provide a different context for each:
- If
system-instance
metadata is requested, the tenant / system instance ID needs to be specified - If
system-version
metadata is requested, the system type and system version must be specified. - If
system-type
metadata is requested, only the system type must be specified and the latest system version is returned.
Relation to system instance aware
The perspectives
attribute deprecates the systemInstanceAware
attribute.
With systemInstanceAware
it was already possible to define whether metadata was dynamic (different per system instance) or not.
But the concept did not allow to describe the same resource in different perspectives and also did not define how the perspectives build upon each other.
ORD Provider Considerations
The following diagram gives an overview which perspectives need to be described by an ORD Provider:
If the system has only static metadata, it should explicitly use the system-version
perspective and state its version (describedSystemVersion
).
If the system has dynamic metadata, it should describe both perspectives completely, if possible.
⏩ See also: Correct Use of Perspectives.
ORD Aggregator Considerations
Static Aggregators
Static aggregators only describe the system-version
perspective.
- If both perspectives are described, it MUST only pick the
system-version
perspective - If only
system-instance
(or unspecified) perspective is available, we assume this is a generic system instance which is meant to describe all system instances as a subsidiary
Dynamic Aggregators
If the aggregator supports both static and dynamic perspectives:
- The ORD aggregator that to be able to aggregate and store both perspectives at the same time.
- In its ORD Service API for consumers, it needs to implement the inheritance / fallback behavior.
If the system-version
perspective is used, the described version MUST be provided via the ORD describedSystemVersion
.version
property.
Ideally, ORD providers SHOULD define the describedSystemVersion
.version
property on both the static and the dynamic perspective.
The version
becomes effectively the "join" criteria how the dynamic metadata is associated to the static metadata.
Some addition considerations that need to be looked into:
- An older version of an application / service can have a resource which has been decommissioned (via a
Tombstone
) in a newer version.- The inheritance / fallback logic MUST not fall back to the now removed resource.