Version 0.9.0

5 Cross-Cutting Requirements

Building blocks are responsible for meeting all cross-cutting requirements or specifying why specific requirements do not apply. Govstack compliance and certification processes will validate these requirements.

5.1 APIs MUST Return a Response within 60 Seconds

5.2 MUST follow TM Forum Specification REST API Design Guidelines Part 1

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

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.

5.5 MUST Only Use TIOBE Top 25 Languages

5.6 MUST Use API-only Based Decoupling

5.7 SHOULD Follow the Amazon API Mandate

  1. 1.
    All teams will henceforth expose their data and functionality through service interfaces.
  2. 2.
    Teams must communicate with each other through these interfaces.
  3. 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. 4.
    It doesn’t matter what technology is used [ed: internally]. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.
  5. 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. 6.
    Anyone who doesn’t do this will be fired. Is this enforcable?

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

Thse should be run across the code base and dependencies, e.g. and/or .

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

5.17 MUST Provide Configuration Only through the Environment

No configuration in code, use environment variables wherever possible

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

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.

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.

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

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

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.

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.

5.31 MUST Closely Model the Organization/Roles Being Automated

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

5.33 MUST Use Standardized Data Formats for Interchange

JSON is used for data models/services. See

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.

5.35 I/O Sanitization MUST be Used

  • See an example 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

5.37 MUST Provide a Compliance Test Kit

Must provide a runnable to ensure compliance
Part of building block design

5.38 MUST Use Web Hooks for Callbacks

5.39 MUST be Internationalizable

5.40 MUST Follow Best Practices for Public Code

See and practices outlined here:

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

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.
Copyright © 2022