5 Cross-Cutting Requirements
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
See:
Some key principles from these design guidelines are as follows:
APIs MUST not include Personally Identifiable Information (PII) or 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 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 , or as —none of which are the server's internal representation.
Resource manipulation through representations. When a client holds a representation of a resource, including any 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 .
See:
Paraphrased from the Amazon API Mandate:
All BBs must expose their data and functionality through service interfaces (APIs).
Building Blocks communicate with each other through these interfaces.
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.
It doesn’t matter what technology is used. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.
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.
Building blocks MUST NOT use shared databases, file systems or memory for data exchange with other building blocks.
Use semantic versioning when documenting changes to API definitions. Any breaking changes to APIs MUST use a different endpoint, as shown here: e.g. /api/v1 and /api/v2
Documentation on the installation and use of the Building Block MUST be provided. Where possible, this documentation SHOULD be stored alongside code in a repository. Documentation MAY be generated from code where applicable.
Each building block’s service APIs MUST be defined and exposed using a standardized machine-readable language. External APIs are described using the OpenAPI 3.x specification. See the following resources for additional information:
Each building block MUST be ready to be deployed as independent container images. Source code and build instructions SHOULD be committed to a public code repository where possible.
A building block may be composed with Kubernetes or docker compose. All build files must be included alongside the source code.
When a building block requires deployment tools such as Kubernetes or Ansible, configuration and deployment scripts should be included in the building block repository. Use of this type of deployment configuration will make individual components of the building block independently scalable and make building blocks less monolithic and more efficient.
Building Blocks MUST conform to GDPR principles, including the right to be forgotten account deletion, and privacy requirements to protect the rights of individuals. Note that these requirements may vary by region, and building blocks must conform to regulatory requirements wherever they are deployed.
Building Blocks MUST have a mechanism for generating logging information. This may be as simple as using STDOUT and capturing through docker logs, or may use other log sinking technologies.
When Building Blocks require callback functionality, they must use webhooks and not direct links to functions within the building block.
All Building Blocks MUST support secure HTTPS transport with TLS 1.3 and insecure cyphers disabled.
API calls SHOULD be able to be made independently of one another. Each API call should contains all of the data necessary to complete itself successfully.
Transactions that cross multiple services SHOULD provide a correlation ID that is passed with every request and response. This allows for easier tracing and tracking of a specific transaction.
Some blocks may require the use of security keys. Those that do must have clearly defined key rotation policies to enhance security
Database processing tools like triggers and stored procedures should be avoided.
Each building block MUST be capable of running independently, without requiring other dependencies such as external data stores or other building blocks.
Configuration MUST be done using secure processes, such as environment variables or a secure secret store.
Designs should support occasional connectivity/low bandwidth, and should allow for asynchronous communication between building blocks. A Publish/Subscribe design pattern can be used to handle changes, allowing loosely-coupled solutions to be assembled without changing existing APIs.
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.
Building blocks SHOULD validate all incoming data to ensure that it conforms with the expected format and type. APIs should also sanitize incoming data, removing any unsafe characters or tokens.
Where a building block has a human user interaction, it SHOULD be able to present information to the user in their local language. Building blocks should be designed to support multiple locales.
Where precise timestamps are required, building blocks SHOULD leverage Network Time Protocol (NTP) to synchronize timestamps between servers.
Software development best practices are recommended for all building blocks. The following guidelines should be followed as part of the software development process.
No languages, frameworks, or dependencies should be used in a building block where that component has an EOL of less than 5 years.
Where possible, building blocks SHOULD be written using commonly used languages to ensure ongoing maintenance and support are as easy as possible. Building blocks MAY leverage less common languages, such as shell scripting where needed.
Building blocks should include tests that provide both unit and integration test coverage
See
GET and PUT APIs (as well as HEAD, OPTIONS, and TRACE) must be idempotent, returning the same value if called multiple times. POST and DELETE APIs will not be idempotent as they change the underlying data. Reference for more information.
JSON SHOULD be used for data models/services wherever possible. See . Where JSON exhange is not possible, building blocks must use other standard data formats (such as XML).
Building blocks and building block solutions MUST leverage existing standards, especially those listed in the below.
A building block MAY provide a mock testing implementation of API functionality to show example endpoints and data payloads. See for additional information.
See
These should be run across the code base and dependencies, e.g. and/or .
See and practices outlined here: