Notes for API Host Developers

Architecture Summary

• In OpenAssetIO, a 'host' is an application, tool or script that makes use of the API to interact with an Asset Management System. This could be anything from a simple pipeline script to a full-blown Digital Content Creation application. We use this term as the host is the thing responsible for 'hosting' the API, and instantiating one or more instances of the API classes that represent an asset management system.
• Hosts interact with an Asset Management System through an instance of the Manager class. The ManagerFactory class is used to instantiate this instance for any given manager. The Manager class wraps the implementation of the API by a specific asset manager to help with state management.
• In order to use the API, every host must provide an implementation of the HostInterface class. This represents the application or tool in a generic fashion to the asset management system. This allows the manager to adapt its behavior if necessary.
• The specific implementation of the HostInterface class provided by a host when creating a ManagerFactory is wrapped in the Host class before being exposed to the manager. This is to allow for assorted middleware auditing/logging functionality, and provide a degree of isolation against future API changes.
• The main currency in the interactions with a manager is the Entity Reference. These are URIs that uniquely identify an entity within the management system. The form of an entity reference is entirely determined by the manager. They must be considered to be opaque handles by the host, even if they look like well-formed strings.
• Nearly all interactions with a Manager require an appropriately configured Context. This tells the Asset Management System about the intended actions of the host. For example, whether an Entity Reference is being resolved for read or for write.
• The lifetime of the Context can be carefully managed by the host to allow the manager to correlate and time-lock disparate API calls.
• It's in the host's interest to provide as much information in the Context and any entity or locale Specifications supplied to API calls as possible. For example, it is strongly advised to use or extend standard locales depending on which part of a host is making API calls. This allows the manager to correctly filter assets or adapt its behavior as required.
• You should resolve an entity reference with the minimal set of traits required, and use resulting data as the authoritative source of information about an asset. For example, to determine the final colorspace of an image.
• If the manager executes code from Python, then the Global Interpreter Lock (GIL) will be released before executing any C++ implementation of the HostInterface and LoggerInterface class methods. Similarly for methods of the ManagerImplementationFactoryInterface class (though this is an implementation detail of the plugin system and only of concern in advanced use cases).

Recommended Reading

See also

Entities, Traits and Specifications

ManagerFactory

Manager

Context

Implementation Check List

Required for Simple Resolution

• Implement the HostInterface class methods: identifier and displayName.

• Use ManagerFactory.defaultManagerForInterface to bootstrap the API, provide the following objects:

  • An instance of the custom class derived from HostInterface.
  • A logger (derived from LoggerInterface), for simple console logging you can use a ConsoleLogger wrapped in a SeverityFilter.
  • A ManagerImplementationFactoryInterface capable of instantiating managers. In the majority of cases a default-configured PythonPluginSystemManagerImplementationFactory will be sufficient.

  Note that in some environments, a default manager may not be configured. As a host, can error here, or choose to present the user with an additional manual configuration mechanism for your specific API session if you so wish.

• Ask the manager if it supports the resolution workflow by calling Manager.hasCapability, passing kResolution.
• Create (and configure) a Context as appropriate for calls to the API. Re-use context objects for all API calls that are related to the same user session or logical set of interactions. For example, one per document or working environment.
• Ask the manager if they support resolve for the relevant data by supplying its Trait Set to Manager.managementPolicy with a Context with kRead access, respecting the returned traits - this may be a subset if the manager is only capable of resolving some of an entity's traits. Note that management policy is runtime invariant for any given context/access/trait set.
• Always check any suspected entity references with Manager.isEntityReferenceString before passing to any other API calls.
• If you support distributed processing provide a mechanism to persist a Context across processes.
• Provide means for users to 'de-assetize' documents to facilitate sharing outside of the assetized environment. This usually consists of resolving any appropriate traits and substituting entity references or controlled properties with their resolved values.

See also

Initializing the API in a Host

Setting up a Manager

Resolving a Reference

Required for Publishing

• Ask the manager if it supports the publishing workflow by calling Manager.hasCapability, passing kPublishing.
• Ask the manager if they support publishing for the relevant data by supplying its Trait Set to Manager.managementPolicy with a kWrite access, respecting the returned traits. Note that some managers may not be able to persist data for all of an entity's traits, these traits will be omitted from the managementPolicy response.
• Follow the policy, preflight, resolve, write, register process illustrated here whenever generating new data.
• Include in your documentation, any scenarios in which entities are registered to references known to be of a different Trait Set. For example, an editorial application registering the traits of an ImageSpecification to a reference with the traits of a ShotSpecification indicates that the images should be published "under" that shot.

See also

Publishing a File

Recommended

• Present users with the ability to enable and select a manager to use to interact with an Asset Management System, storing applicable options, etc...
• Test and resolve any strings that may represent file system locations (Manager.resolve)
• Ensure the use of a correctly configured Context for all calls to the API.
• If a manager's managementPolicy sets the WantsThumbnail trait, where possible, generate thumbnails as requested during publishing.
• Create specifications for any custom 'asset types' you may deal with.

See also

Generating a Thumbnail During Publish