An Application Programming Interface (API) is a construct that enables communication between systems. Integration between systems in complex environments continues to be a business priority to support automation activities. An API can be purpose-built for a bespoke integration (typical of legacy systems), or alternatively a standard connector can be developed between industry standard systems such as ERP’s and Service Management platforms. Managing these integrations becomes a complex operational task as updates and new releases to the integrated systems (and enabling technologies), can lead to intensive release management and testing activities. Security is also of utmost concern when managing integrations as the API provides a potential entry-point from either system integration direction – the API has become a preferred target for malicious attacks on systems and networks.
The need to have a well-architected catalogue of the API’s that exist within an organisation is clear. Furthermore, identifying and modelling the relationships that exist between the integrations and their respective applications (within the context of the broader Enterprise Architecture Repository) provides immense value to business and technical stakeholders. QualiWare now supports a range of new templates to enable enterprise architects to model APIs within their existing EA repository. These templates are automatically leveraged upon the creation of an API using OpenAPI.
Architecting APIs in QualiWare can be automated using our new Web Ontology Diagrams (also expanded further in the Centre of Excellence), and the APIs themselves can be tested and interacted with directly from the QualiWare front-end by leveraging our adoption of the OpenAPI specification – this is expanded on below.
Business Value
- A new set of model templates for architecting APIs
- A way to automatically model an API by leveraging web ontology diagrams (also a new set of QualiWare templates)
- New ways for technical teams to manage the transformation of legacy APIs into standard RESTful web services
- The ability to identify and manage integration points as they relate to the security, stability, and recovery of systems
- A new architecture layer that directly supports the adoption of Digital Twin, Augmented Reality & Metaverse initiatives
- A more complete EA repository is enabled by the inclusion of API model templates
API Architecture Guide
This guide will demonstrate a typical output of what the result would be of architecting and interacting with an API in QualiWare.
The OpenAPI can be accessed primarily through the repository explorer, or alternatively by navigating to the respective integration which will be covered in more detail further on. To access it via the repository explorer, open the repository explorer and type “OpenAPI” (1) to view all the templates related to API. Interacting with the API is achieved by opening the relevant DocRoot:OpenAPI (2) model, for the purpose of this example we are using the RealEstateCore Core Module (3).
An alternative way to access the API would be to navigate through to where the actual integration takes place. In this example, using the EA role I am going to navigate to the Enterprise Architecture (4) page and select the Application Landscape (5).
Once the application landscape diagram has been opened, I can then select the Mobile PAX Service Platform (6), and then select its linked model (7) to view the application in more detail.
In the following diagram, since I am interested in the integration between the two platforms, I select the connector (8) between “Location Info” and the Mobile Pax Service Platform. That will bring up a property window of associated objects, I can then select the PAXDataIF (9) object which contains the actual API. Thereafter, I can now select the RealEstate Core Module (10) to get direct access to the API DocRoot.
The Core Module opens an automatically generated extract of the documentation relevant for the selected API. Using this feature, users can interact with the API by leveraging the ability to test API calls. The generated API retrieves the set of root ontologies that form part of the OpenAPI standard. These endpoints can be interacted with to Get, Create, Update or Delete entities and objects between integrated systems.
Selecting an endpoint (11), the view changes to enable interaction with that specific function (request etc.). Since the API is generated based on an OpenAPI standard, standard requirements for creating a new object are highlighted (12). Expected responses are also provided in the event of an error. (13)
If a specific code language is required, a sample of the code can be generated by selecting the relevant language from the dropdown list (14). When a new language is selected, the view changes to reflect a sample code in that language (15).
The user can now enter the parameter that they would like to send via the API – in this example, I want to create a new GeoReferenceOrigo object that is called GeoObjectTest. I can enter this entity name in the parameter entity field (16), and this will be reflected immediately in the code sample (17). If the user clicks send API request, it will attempt to send the code including the parameters to create the new object in the integrated system (18).
The potential to leverage the value of testing integrations using OpenAPI, and encourage stable and consistent API requests becomes evident when all integrated systems can take advantage of the standards introduced using the QualiWare API Architecture capabilities.