Notes of an IT Architect - страница 7

Systems can communicate in various ways:

* integration request (normal synchronous request-response),

* remote procedure call (RPC),

* sending a command to the queue (from the supplier to the consumer directly through the event queue),

* publish-subscribe, Push-Sub (sending events to a common queue, from which groups of events are retrieved from the system in advance, undefined by the provider),

* packet data transmission,

* transferring files to storage,

* streaming data.

The interactions themselves should be described, and preferably unified. To describe functional or non-functional parameters (response time, availability, message size, bandwidth) of interactions between the supplier and the consumer, a Contract is used, which the supplier undertakes to fulfill. Functional parameters are described using the Application Programming Interface (API). Service APIs can be divided into groups based on message format (DTO, JSON, XML, binary) or protocol (HTTP, REST, SOAP). It is important to specify in the API contract: ID, name, version, purpose, template, specification of input and output parameters. The API itself will contain methods (encouraging the consumer to take data, change, allocate, etc.). Parameters passed in a method are described by a method specification, for example, using OpenAPI or Swagger. For many languages, and primarily for the Java language, you can automatically generate a specification for OpenAPI using Swagger by Javadoc annotations (by special comments) in the code. The specification will be displayed in both text formats (JSON and YAML) and graphical. For ease of design, you can use the Swagger Editor (https://swagger.io/tools/swagger-editor/). This helps to organize automated contract testing. In general, the presence of the specification helps to organize API-first development, when the API specification is first written, and already the application code is developed for it, implementing it.

To bind an API to the system providing it, the endpoint concept is used. Endpoint is described either by an address with a port, or MMT, hiding them. APIs are described by a machine-readable description (declaration), for example Java interface and WSDL document.

The API life cycle is close in stages to the software life cycle and the following cycle stages can be outlined: requirements gathering, interface design, implementation, testing, operation, and decommissioning stages: decommissioning warning (marked as obsolete to avoid new users), decommissioning (tracking the decrease of existing users), disposal (closing access to the API and removing it), and the stage of creating a new version. The new version of the API can be compatible and incompatible with the old one, for this you can differentiate them by semantic versioning into incompatible with the previous version, compatible with the previous version and bug fixes. By semantic versioning, the version can be written as "major.minor.patch", for example 1.9.0 – > 1.10.0 – > 1.11.0.

The solution integration layer is described in the conceptual architecture. The conceptual framework only indicates integration. It is intended for coordination with stakeholders: architects of the integrated solution, corporate architect responsible for the landscape, product owners, owner of the variable landscape, security service, resource provision service (infrastructure department) for its quick approval. The content is indicated in the target architecture (detailed architecture) of the solution. She participates in the early stages of creating a service and in the acceptance tests of the solution within the framework of architectural control. The conceptual architecture is the source of artifacts for implementing and developing a detailed solution architecture. We can distinguish the following stages of creating a conceptual architecture: planning, creation, development of an incremental draft (sketch), approval, revision. In order for the diagrams to be understood by both the developer and the owner of the product, a short description (Architecture Decision Records, ADR) is needed: the goal, the essence of the solution, rejected options, rationale, consequences, affected systems, a link to the diagram and the originator's contacts.