Key Digital Functionalities and Cross-Cutting requirements

KDF1

Routes requests to the correct provider after necessary message transformation functionalities and protocol conversion

KDF2

Connects the service requestor to the service provider and its underlying solution platforms, realizing the requested service

KDF3

Discovers services and, at runtime, to support the virtualization of services, so that changes to end-points can occur without impact to service consumers and service providers

KDF5

Enforces access privileges and other security policies

KDF6

Maintains service invocation history and monitors and tracks service invocations

KDF7

Provides broadcast/multicast capabilities to facilitate faster, more resilient application design

5.1

APIs MUST Return a Response within 60 Seconds

5.2

MUST follow TM Forum Specification REST API Design Guidelines Part 1

See https://drive.google.com/file/d/1lpl1IzLGzvbXALW4jqDxLAKqfwuJyeXy/view?usp=sharing

5.3

SHOULD follow TM Forum Specification REST API Design Guidelines Parts 2-7

See https://drive.google.com/drive/u/2/folders/1eS20wt_PP7CoJEOvzagYDTTMCfmv3y6l

5.4

EOL MUST be at Least 5 Years

Nothing SHALL be used in a block that has an EOL of less than 5 years.

How this requirement should be interpreted?

5.5

MUST Only Use TIOBE Top 25 Languages

See https://www.tiobe.com/tiobe-index/

SHOULD use TIOBE top 25 languages (Not MUST)
Shell may be used for scripting. (Shell holds language ranks between 50 and 100.)

Java, TypeScript

5.6

MUST Use API-only Based Decoupling

UI, Backend API and Backend business logic are separated.

5.7

SHOULD Follow the Amazon API Mandate

See https://api-university.com/blog/the-api-mandate/

1. All teams will henceforth expose their data and functionality through service interfaces.

2. Teams must communicate with each other through these interfaces.

3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.

4. It doesn’t matter what technology is used [ed: internally].HTTP, Corba, Pubsub, customprotocols — doesn’t matter.

5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.

6. Anyone who doesn’t do this will be fired. Is this enforceable?

PubSub service is a core component for enabling async communication IM-BB.

5.8

APIs MUST be Idempotent

Paraphrased from Wikipedia: APIs can be called multiple times without changing the result beyond the initial application.

5.9

Stateless APIs SHOULD be Used Wherever Possible to Enhance Scalability

5.10

Regular Security and Code Quality Audits MUST be Run

These should be run across the code base and dependencies, e.g. https://www.sonarqube.org/and/ or https://snyk.io/ .

5.11

MUST Include Integration Test Coverage

5.12

MUST Include Support for a Log Sink

5.13

Data Models MUST Include Version Numbers

5.14

APIs MUST be Versioned

As shown here: e.g. /api/v1 and /api/v2

5.15

API Calls MUST Include Transaction/Trace/Correlation IDs

5.16

MUST Use Semantic Versioning

See Semantic Versioning 2.0.0

5.17

MUST Provide Configuration Only through the Environment

No configuration in code, use environment variables wherever possible.

Configuration not only through environment.
Configuration is mainly in configuration files. Environment variables could also be used. No configuration in code.

5.18

MUST Include Clearly-Defined Key Rotation Policies

Some blocks may require the use of security keys. Those that do must have clearly defined key rotation policies to enhance security.

5.19

Documentation MUST be Generated from Code and/or Checked in Alongside Source Code

OpenAPI definition(s) are generated by the applications.

5.20

MUST Not Use Shared Database/Filesystem/Memory

interconnection uses APIs only

5.21

Databases MUST Not Include Business Logic

This means no triggers/stored procedures shall be used.

Databases SHOULD not include business logic.

We propose that this is a design recommendation which intends to make business logic all live in a clearly visible and accessible location. This may not always be followed, as the benefits of stored procedures (e.g., in reducing DB transaction round-trips, etc.) may sometimes outweigh this general design recommendation.

5.22

MUST Enforce Transport Security

HTTPS with TLS 1.3 and insecure cyphers disabled.

5.23

MUST Only Use Unicode for Text

5.24

MUST Use ISO8601/UTC for Timestamps

5.25

MUST Follow REST Design Principles

MUST not include  PII/session keys in URLs - use POST or other methods for this MUST support caching/retries

• Resource identification in requests

  Individual resources are identified in requests, for example using URIs in RESTful Web services. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server could send data from its database as HTML, XML or as JSON—none of which are the server's internal representation.

• Resource manipulation through representations

  When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource's state.

• Self-descriptive messages

  Each message includes enough information to describe how to process the message. For example, which parser to invoke can be specified by a media type.[3]

See https://en.wikipedia.org/wiki/Representational_state_transfer for more.

5.26

MUST be Asynchronous First

• When entities change, they publish events, allowing loosely-coupled solutions to be assembled without changing existing APIs. Supports occasional connectivity/low bandwidth

SHOULD be asynchronous first

The Service Access Layer of IM is synchronous first.
The PubSub Layer is asynchronous

PubSub enables async first approach but is not asynchronous when responding to requests.

5.27

MUST Support Both SAAS and Do-It-Yourself

• Many new governments prefer cloud-based deployments

• SAAS is preferred to make it easy for companies to provide new services

• Anyone should be able to test/deploy building blocks by themselves

Solution is Kubernetes deployable.

5.28

MUST be Autonomous

Each block must be capable of running independently.

5.29

MUST be Open-source Only with No Vendor Lock-in

Each block must be composed of open-source software unless there are no alternatives.

Solution is comprised of technologies under either Apache 2.0 or MIT License

5.30

MUST be Cloud Native

• Each block MUST be ready to be deployed as independent Docker images, with complete source code and build instructions committed to GitHub.

• A block may be composed with Kubernetes or docker compose. All build files must be included alongside the source code.

Is delivered as deployable cloud native images.

5.31

MUST Closely Model the Organization/Roles Being Automated

See https://en.wikipedia.org/wiki/Conway%27s_law

The PubSub adopts the authorization model used by X-Road.

5.32

MUST Use Standardized Configuration

• Configuration MUST only happen through environment variables or secrets

• Allows visual construction of blocks, perhaps with domain modeling tools

See 5.17

5.33

MUST Use Standardized Data Formats for Interchange

JSON is used for data models/services. See https://www.json.org/json-en.html

5.34

MUST Use Existing Standards for Data Interchange, Where Available

If an existing standard is available, it should be used, e.g. DICOM/Hl7/FHIR for healthcare. TMForum has a large library of standardized APIs and data models that can be used.

Standard formats are used for communication with other BB.
Inside BB non-standard protocols can be used.

Non-relevant to IM-BB and/or complies.

5.35

I/O Sanitization MUST be Used

• See an example JSON Schema for JSON data.

• Follows Postel’s law: be liberal in what you consume but strict in what you emit

5.36

MUST Include Machine-Readable API descriptions

• Each block’s service APIs are defined using a standardized machine-readable language. External APIs are described using the OpenAPI 3.0 specification for APIs: https://swagger.io/docs/specification/about/

5.37

MUST Provide a Compliance Test Kit

• Must provide a runnable Postman: The World's Leading API Platform | Sign Up for Free to ensure compliance

• Part of building block design

5.38

MUST Use Web Hooks for Callbacks

OpenAPI spec 3.0 supported in the first version. Moving to OpenAPI 3.1 is planned in the future.

PubSub itself does not need to have webhooks. The requirement is for the services consuming the PubSub PUSH events.

5.39

MUST be Internationalizable

5.40

MUST Follow Best Practices for Public Code

Seehttps://standard.publiccode.net/ and practicesoutlined here:

• Code in the Open

• Bundle Policy and Source Code

• Create Reusable and Portable Code

• Welcome Contributions

• Maintain Version Control

• Require Review of Contributions

• Document Your Objectives

• Document your code

• Use plain English

• Use open standards

• Use continuous integration

• Publish with an open license

• Use a coherent style

• Pay attention to codebase maturity

5.41

MUST Follow Strict Requirements Around NTP/RTC Synchronization

5.42

If an API Response will Take Longer than 5 Seconds, you SHOULD Return a Ticket with a
Suggested Callback Time that is Resolved by Polling

PubSub itself does not perform complex business logic that would exceed 5 seconds.

As this requirement does not deliver any value, it is not implemented.

5.43

MUST use STDOUT/ERR for Logging, to be Captured by the Docker/Container Environment

• Each block MUST be ready to be deployed as independent Docker images, with complete source code and build instructions committed to GitHub

• A block may be composed with Kubernetes or docker compose. All build files must be included alongside the source code.

5.44

SHOULD Include Kubernetes or Ansible Scripts

In addition to Docker Compose for more efficient and scalable deployments. This will make individual components of the building block independently scalable and make building blocks less monolithic and more efficient,

5.45

SHOULD Comply with GDPR Principles

Include the right to be forgotten account deletion), privacy requirements to protect the rights of individuals, etc. Note that these requirements may vary by region.

5.46

MUST Implement Existing Standards Where Possible

Building blocks and building block solutions MUST leverage existing standards, especially those listed in the Standards section below.

MUST allow the provisioning/management of admin users via the SSO/IAM application specified by the Security BB. 

Support for OIDC compliant IAM added to both PubSub and X-Road