|This page documents the definition of service interfaces and the generation of service clients and service stubs. It also describes run-time validation of these interfaces.|
The figure below shows the process for definition system interfaces and generation implementation level and system run-time level artifacts from these interfaces:
The main steps of this process are:
- Authoring of interfaces, e.g. in Enterprise Architect or a Database tool. Interfaces include services, objects (resources), UI elements and others
- Definition of interfaces in machine-readable form, e.g. in YML or CSV files.
- Generation of stubs and clients used during development time
- Loading of the system interfaces into the system registries during bootstrap
- Adding and updating system interfaces during run time
Since ION R2, YAML (YML) files are used to define service interfaces. Service interfaces are manually defined and maintained in YML files by the architecture team.
Each service definition provides:
- Service description: name, documentation, link to spec
- Service dependencies on other services
- List of operations. Each operation definition provides:
- Operation name, documentation
- Operation input arguments
- Operation output arguments
- Operation exceptions raised
Operation input and output definitions are lists of named and typed arguments. Arguments may be of a basic type or of an ION object type.
During development time, the service interface files are translated into service programming artifacts (e.g. clients, base classes, interface classes) by the generate_interfaces script.
The generate_interfaces script takes the service definitions, in YAML, and transforms them into Python code that can be imported/used or inherited from. See [here] for the fine details.
The Capability Container enforces the following conditions:
On the service provider side:
This check happens in the validation interceptor. Checks include:
- Arguments are provided exactly as specified in the interface
- No additional arguments are allowed
- Arguments are either not present (if optional), or present and of the exact type
- Note: sub-types are allowed. E.g. if Resource type is specified, any sub-type such as InstrumentDevice is possible
- ID types are are checked (see Resource Identifiers)
On the service requester side:
These checks happen in the generated service clients and their base classes. Checks include:
- Any allowed arguments and types can be sent
By a third party observer:
The intent is