Administration API/alx

Administration API
Contributors	Roland Bijvank, Wiebe Wiersema, Christian Köppe
Last modification	May 17, 2017
Source	Bijvank, Wiersema & Köppe (2013)
Pattern formats	OPR Alexandrian
Usability
Learning domain
Stakeholders

Context:

Software systems that are deployed in a professional environment often need to be maintained by a system administrator, e.g. accounting software or software in a company that is used for managing customer relationships. These administration tasks include adding or removing users, updating the system to a new version, or establish and maintain connections to other third party software. Most applications provide an administrative interface for system administrators to perform these tasks.

***

Problem and forces:

If the administrative interface is a GUI, many of the standard administration tasks can not be easily automated. Repetitive tasks have to be manually completed again and again, which leads to a high frustration of the administrators. It also can be hard to get remote access to such a GUI.

Unexpected Automation Demand. Good system administrators have their own ways of organizing their administration tasks. They strive to automate many parts, often in unexpected ways, and a GUI minimizes the possibilities of doing so.

Platform Diversity. The operating systems—e.g. Windows, Unix, or MacOS—which administrators are using for their administration tasks frequently differ from the OS the application to be administered is running on.

Rise of the Cloud. The lower cost to deploy systems in the Cloud leads to more systems being deployed and subsequently to a higher workload for the system administrators if they do not adopt more efficient means for system administration.

Increasing Rate of Upgrades and Deploys. The Agile and DevOps development lifecycles where software upgrades are deployed on a weekly or even a daily basis, as opposed to the quarterly and yearly deploy cycles of more traditional software development methods, imposes tight control, predictability and efficiency on the deploy, installation and configuration of software

***

Therefore: Provide an API for all required administration functionality. Make this API externally available, easily accessible—e.g. with a serializable or command line interface—and well documented, so that admins can automate administrative tasks and integrate it easily in the administration processes.

Solution description:

Offering an administration API provides much more flexibility for the system administrators to administer the systems in the way they think fits best. It gives them enough freedom to integrate the administration in existing processes. In order to be able to offer this high degree of freedom regarding the usage of the API, the system developers have to carefully design it and to offer the administration functionality in appropriate abstraction levels. This means that the API should be fine-grained enough.

The tasks of the system administrators are quite wide e.g.: installation, maintenance, scheduling repair, performance monitoring, backup & recovery, defining and maintaining usage and security policies etc. For most of these tasks an API can increase the efficiency and quality of the administration processes.

Automating administrative tasks reduces the number of errors that normally occur in manual execution such as the omission of steps or typing errors in commands. In a script such errors will also occur while programming the script, but once discovered can be fixed for subsequent usage of the script.

Tools for automation can make use of the administration functionality if they can connect to the provided API. For example, the right API helps to automate tasks that are part of a new employee account creation process.

To securely expose administrative features utilize a Proxy (Proxy) The Proxy (Proxy) can include an authentication and authorization mechanism and block all unauthorized access attempts. This will be discussed in more detail in the implementation description below.

If the system evolves, the API is also likely to change which might require adaptations the system developers are not aware of. This is a general problem in interface- and component-based development and needs to be addressed in the design of the API too.

Providing an API might require more elaborate documentation compared to a more intuitive and self-explaining administrative GUI. The allocation of user roles using such API might e.g. require the correct spelling of the user role names. A misspelling of these names can lead to errors or have other unwanted effects. A GUI can offer a selection list including all user roles and possibly an extra explanation of these roles in a separate window section. This minimizes the need for extra documentation. The API should therefore include an extensive help, containing all information necessary for using the provided administration functionality. For the same reason the API should include a good exception handling in combination with clear error messages.

In the most simple cases the pattern is a specific variant of a Service Layer (Service Layer) In this case it does not contain any logic, but simply forwards all requests to already existing configuration subsystems that offer the administration functionality. How these internal configuration subsystems are implemented is hidden to the user of the administration API. They can use this administration API using their own administration tools, e.g. a GUI or automated scripts. This is shown in Figure 1.

Fig. 1 Main solution structure of Provide an Administration API (Provide an Administration API)

If the administration API should not be publicly available due to security reasons, a Proxy (Proxy)could be used to adequately address this issue. Figure 2 shows the main design. The protection proxy needs to include some mechanism for authentication and authorization of the requester.

Fig. 2 An administration API including a protection proxy for security reasons

In certain cases the implementation language of the system and that of the administration API are different. Main reason for this could be that the administration API is required to be provided in a specific scripting language that suits the administrators’ tasks best. In that case the administration API subsystem also becomes a specific kind of an ADAPTERbetween these two implementation languages.

***

Rationale:

The problem of different platforms used for the system and in the administration environment can be minimized by making use of cross-platform scripting languages like Python, Ruby or TCL. This is also a certain advantage above graphical administration interfaces, as it removes the platform-specific issues caused by the GUI technologies. In combination with such a cross-platform scripting language this pattern shows its real strength as one can uniformly approach the administration API on any given platform.

Ideally, any changes in the system itself do not lead to changes in the administration API. However, if also functionality of the system regarding its configuration is changing, then also the API likely needs to be changed. The tools of the administrators are dependent on the API both syntactically and semantically in varying degrees. Unfortunately are both dependency types interrelated: the less syntactic the dependency is, the higher it is semantically and vice versa. One criterion that can be used for determining if the API should decrease the syntactic or the semantic dependencies is how easy it is to adapt the connection to the API on either syntactic and semantic level. If the interfaces are easy to adapt on both sides, then one should prefer more syntactically dependent interfaces that explicitly contain the semantic information in the naming of the methods and parameters. If the interfaces are not easy to adapt, then the syntactical dependencies should be low by using more generic interfaces that merely require different parameter contents but no interface adaptations.

Known uses:

Microsoft Sharepoint 2013 provides a rich set of APIs. Especially the server object model API offers all required functionality for administration tasks as “backup, farm health and diagnostics, logging, farm and web application management, upgrade, deployment, caching, and Windows PowerShell customization."

Another known use of this pattern can be found in Software-Defined Networking. This networking architecture is designed to use standardized APIs for defining and reconfiguring the way data and resources are handled within a network and to make interfacing and reconfiguring the network and its components easier.

One possibility of implementing this administrative API in the Java programming language are Java Management Extensions (JMX.

Google also provides administration APIs for managing Google Apps, e.g. an API for monitoring the activities of account’s administrators or for version conflict detection.