Prefer API to Custom Client Tools

urn:js:virtue:aspire:proposal:1.1

TL;DR

When an integration can be done using an API, this is preferred to remote execution using custom client tools.

Rational

Integrations can be the triggering of events such as a scheduler prompting a reporting system to refresh cached data, where the scheduler could make an API call instead of running a command on a custom client tool.

They could also relate to the acquisition or delivery of data, where the use of an API rather than a custom client tool is not as simple as “use the API instead of the client tool”, because a simple “connect and download the data directly” using a custom client tool might be replaced by an API call to prompt the data source system to generate a file which can then be collected. The design of these integrations will need to be considered on a case by case basis to make sure that getting the benefits of following this principle to prefer APIs to custom client tools is not at the cost of deviating from basic good design principles of simplicity, performance, scalability and reliability.

Simplify integrations, avoid dependency problems and maintain security for integration of Aspire components

Implications

• Reduces the need to install custom client tools on the clients which require integration
  • For example to remotely trigger a cube refresh on MicroStrategy it can be done with an API call, eliminating the need to install the full Command Manager or the Command Manager Runtime on the system doing the refresh. This is easier to set up as compatibility issues between the custom client tools and the system in question do not need to be addressed.
• With well formed APIs, the security profile is generally at least as good or better than with a client tool, and it should be easier to determine that this is the case
  • Client tools may not have been designed with cloud service style third party vendor integrations in mind
  • It’s generally easier to understand what an unfamiliar API is doing and what it exposes than the same for an unfamiliar client tool
• There will generally be less friction on responsible delivery when opening routes for secure API traffic versus requesting firewalls for unusual ports for client tools, as by specifying it’s an API over https, it is not necessary to determine if the custom client tool is encrypting its traffic fully. Workarounds such as SSH tunnelling provide protection but they generate work in the form of SSH key management and/or risk that SSH keys are not handled securely enough.