Archived [2020-03-31] - Directive on Management of Information Technology

activity (activité)

Is the work that is done to achieve an output, such as a product or service. It is a component of a program and may include several levels of activity (i.e., activity, subactivity and sub-subactivity) at the level of detail needed to manage a program and its services successfully.

applications (applications)

Are a subclass of computer software that employs the capabilities of a computer directly and thoroughly for a task that the user wishes to perform.

assets (biens)

Are tangible and intangible items of value that have a life span beyond one year, whether they are Crown-owned, leased or accessed through other arrangements.

Chief Information Officer Council (CIOC) (Conseil des dirigeants principaux de l'information (CDPI))

Refers to the forum for the departmental CIO or his or her equivalent to participate in shared decision making by recommending government-wide information technology options to the Chief Information Officer of Canada. This forum also ensures that departments collectively support decisions made by the CIOC. Details on its operations can be found in the CIOC's Terms of Reference.

client (client)

Is the intended recipient of a service. Clients may be external to the federal government (e.g., citizens, businesses, non-Canadians and non-profit organizations) or internal to government (e.g., departments).

COBIT (COBIT)

Stands for “Control Objectives for Information and related Technology” and represents a set of best practices that provide guidance for the management of IT processes. (Source: IT Governance Institute)

common service (service commun)

Is a service provided by a common service organization.

common service organization (organisme de service commun)

Refers to a department or organization designated as a central supplier of particular services that support the requirements of departments. Common service organizations are listed in Appendix B of the Common Services Policy.

departments (ministères)

Has the same meaning as in section 2 of the Financial Administration Act and includes all departments, agencies, branches and departmental corporations listed in Schedules I, I.1 and II of the Act.

departmental CIO or equivalent (DPI du ministère ou équivalent)

Refers to the senior official designated by the deputy head, as established under Section 6.1.6 of the Policy on Management of Information Technology, to represent the department to TBS on matters relating to IT management. The requirements in this directive do not include all the duties and responsibilities of departmental CIO or equivalent; in addition to IT management, other responsibilities could include information management or IT security.

information technology (technologies de l'information)

Involves both technology infrastructure and IT applications. Technology infrastructure includes any equipment or system that is used in the automatic acquisition, storage, manipulation, management, movement, control, display, switching, interchange, transmission or reception of data or information. IT applications include all matters concerned with the design, development, installation and implementation of information systems and applications to meet business requirements.

investment (investissement)

Is the use of resources with the expectation of a future return, such as an increase in output, income or assets or the acquisition of knowledge or capacity.

interoperability (interopérabilité)

Refers to the ability of departments to operate in synergy through consistent IT management policies, practices, processes and technologies.

IT decision making (prise de décisions en matière de TI)

Refers to the process and actions involved in making decisions on IT management.

IT services (services de TI)

Are services that clients and end user recipients understand as IT service provider outputs. Services may be delivered by providers through one or more internal activities.

ITIL (ITIL)

Stands for “Information Technology Infrastructure Library” and represents a set of best practices that guide IT service management. (Source: ITIL)

management of information technology (gestion des technologies de l'information)

Is planning, acquiring, building, implementing and operating IT assets, systems or services, measuring their performance and arranging their disposal.

service (service)

Refers to a means, administered by a program, of producing a final valued output that addresses one or more target group needs.

service catalogue (catalogue de services)

Is a database or structured document for users that is published by a service provider and includes a full description of individual IT services or, at a minimum, information on cost, quality and service levels. The service catalogue may also include service request processes and contact points.

service costing (établissement du coût des services)

Refers to cost estimating that assists senior management in making decisions on services. (See the TBS Guide to Costing)

shared service (service partagé)

Is a service that is shared by more than one client.

Small Departments and Agencies (petits ministères et organismes)

Organizations with reference levels of less than $300 million per year including revenues credited to the vote

stakeholder (intervenant)

Is an entity that may be internal or external to the federal government, such as a citizen, business, service provider, service consumer, partner or employee, and has an interest in an IT service, project or organization or their related activities, resources or deliverables.

12.1 IT plan

The IT plan is a practical document that defines departmental IT directions, strategies, architecture and HR capacity and how these work together to achieve departmental business and government-wide strategic objectives. The IT plan is to support the effective resource allocation and investment planning decisions of the department through the departmental investment planning process. The IT plan reflects departmental priorities and outlines planned investments, including any acquired services, for the upcoming five-year period (at a minimum) in the following areas:

• New IT projects, systems, services or large enhancements to existing projects, systems and services;
• Planned maintenance of or enhancements to existing IT systems or services; and
• IT operations.

The IT plan is reviewed annually and updated as required at the time of the review. The plan, at a minimum, addresses governance, IT business, performance measures and risk management.

12.1.1 Governance

• Governance includes decision processes for the following areas:
  • IT strategies and policies;
  • Infrastructure;
  • Applications and systems; and
  • Resource allocations.
• IT resource allocation decisions are guided by governance selection and prioritization criteria and methodology.

12.1.2 IT business

• IT plays a role in enabling departmental business outcomes in the context of Section 12.1.
• IT architecture, including but not limited to defined core IT competencies, technology choices and services, should support business outcomes.
• IT should be aligned with departmental and government-wide IT priorities, technology, and common and shared services, when such services are available and appropriate.
• Resource allocation targets are to be organized into the following four portfolio classes:
  • Innovation – resource allocations that focus on transforming the department's business model;
  • Business opportunity – resource allocations that realize measurable business benefits (e.g., revenue or service growth);
  • Maintenance – resource allocations designed to maintain existing service levels (e.g., ongoing operation of IT); and
  • Mandatory – resource allocations required for legal or regulatory compliance.

12.1.3 Performance measures

• Business outcomes and key performance indicators (KPI) are required to measure delivery of core services.
• Performance measures support continuous improvement by monitoring and gating planned IT activities.

12.1.4 IT risk management across the planned activities, which includes the processes and strategies to manage the following:

• Resource allocation;
• Scheduling;
• Business risks (e.g., confidentiality, integrity, availability of core infrastructure and services, and infrastructure renewal); and
• Capacity and sustainability.

12.2 IT progress report

An annual IT progress report addresses resource allocation, schedule changes and the progress achieved against planned activities as well as offers recommendations for the next planning cycle.

• C.1These procedures take effect on December 1, 2018.
• C.2Procedures
  • C.2.1These procedures provide details on the requirements set out in section 6.1.1 of the Directive on Management of Information Technology.
  • C.2.2These procedures will be used by Departmental Enterprise Architecture Review Boards and the Government of Canada Enterprise Architectural Review Board as an assessment framework to review digital initiatives to ensure the GC acts as a single enterprise and to ensure departmental alignment with the Government of Canada digital direction.
  • C.2.3Mandatory procedures are as follows:
    • Business Architecture
      
      • C.2.3.1Align to the GC Business Capability model
        • C.2.3.1.1Define program services as business capabilities to establish a common vocabulary between business, development, and operation
        • C.2.3.1.2Identify capabilities that are common to the GC enterprise and can be shared and reused
        • C.2.3.1.3Model business processes using Business Process Management Notation (BPMN) to identify common enterprise processes
      • C.2.3.2Design for Users First and Deliver with Multidisciplinary Teams
        • C.2.3.2.1Focus on the needs of users, using agile, iterative, and user-centred methods
        • C.2.3.2.2Conform to both accessibility and official languages requirements
        • C.2.3.2.3Include all skillsets required for delivery, including for requirements, design, development, and operations
        • C.2.3.2.4Work across the entire application lifecycle, from development and testing to deployment and operations
        • C.2.3.2.5Ensure quality is considered throughout the Software Development Lifecycle
        • C.2.3.2.6Ensure accountability for privacy is clear
        • C.2.3.2.7Encourage and adopt Test Driven Development (TDD) to improve the trust between Business and IT
      • C.2.3.3Design Systems to be Measurable and Accountable
        • C.2.3.3.1Publish performance expectations for each IT service
        • C.2.3.3.2Make an audit trail available for all transactions to ensure accountability and non repudiation
        • C.2.3.3.3Establish business and IT metrics to enable business outcomes
        • C.2.3.3.4Apply oversight and lifecycle management to digital investments through governance
    • Information Architecture
      
      • C.2.3.4Data Collection
        • C.2.3.4.1Ensure data is collected in a manner that maximizes use and availability of data
        • C.2.3.4.2Ensure data collected aligns to existing enterprise and international standards
        • C.2.3.4.3Where enterprise or international standards don't exist, develop Standards in the open with key subject matter experts
        • C.2.3.4.4Ensure collection of data yields high quality data as per data quality guidelines
        • C.2.3.4.5Ensure data is collected through ethical practices supporting appropriate citizen and business-centric use
        • C.2.3.4.6Data should only be purchased once and should align with international standards
        • C.2.3.4.7Where necessary, ensure collaboration with department/ agency data stewards/ custodians, other levels of government, and Indigenous people
      • C.2.3.5Data Management
        • C.2.3.5.1Demonstrate alignment with enterprise and departmental data governance and strategies
        • C.2.3.5.2Ensure accountability for data roles and responsibilities
        • C.2.3.5.3Design to maximize data use and availability
      • C.2.3.6Data Storage
        • C.2.3.6.1Ensure data is stored in a secure manner in accordance with the National Cyber Security Strategy, and the Privacy Act
        • C.2.3.6.2Follow existing retention and disposition schedules
        • C.2.3.6.3Ensure data is stored in a way to facilitate easy data discoverability, accessibility, and interoperability
      • C.2.3.7Data Sharing
        • C.2.3.7.1Data should be shared openly by default as per the Directive on Open Government
        • C.2.3.7.2Ensure government-held data can be combined with data from other sources enabling interoperability and interpretability through for internal and external use
        • C.2.3.7.3Reduce the collection of redundant data
        • C.2.3.7.4Reuse existing data where possible
        • C.2.3.7.5Encourage data sharing and collaboration
    • Application Architecture
      
      • C.2.3.8Use Open Standards and Solutions by Default
        • C.2.3.8.1Where possible, use open standards and open source software first
        • C.2.3.8.2If an open source option is not available or does not meet user needs, favour platform-agnostic COTS over proprietary COTS, avoiding technology dependency, allowing for substitutability and interoperability
        • C.2.3.8.3If a custom-built application is the appropriate option, by default any source code written by the government must be released in an open format via Government of Canada websites and services designated by the Treasury Board of Canada Secretariat
        • C.2.3.8.4All source code must be released under an appropriate open source software license
        • C.2.3.8.5Expose public data to implement Open Data and Open Information initiatives
      • C.2.3.9Maximize Reuse
        • C.2.3.9.1Leverage and reuse existing solutions, components, and processes
        • C.2.3.9.2Select enterprise and cluster solutions over department-specific solutions
        • C.2.3.9.3Achieve simplification by minimizing duplication of components and adhering to relevant standards
        • C.2.3.9.4Inform the GC EARB about departmental investments and innovations
        • C.2.3.9.5Share code publicly when appropriate, and when not, share within the Government of Canada
      • C.2.3.10Enable Interoperability
        • C.2.3.10.1Expose all functionality as services
        • C.2.3.10.2Use microservices built around business capabilities. Scope each service to a single purpose
        • C.2.3.10.3Run each IT service in its own process and have it communicate with other IT services through a well-defined interface, such as an HTTPS-based application programming interface (API) as per Appendix D: Mandatory Procedures for Application Programming Interfaces
        • C.2.3.10.4Run applications in containers
        • C.2.3.10.5Leverage the GC Digital Exchange Platform for components such as the API Store, Messaging, and the GC Service Bus
    • Technology Architecture
      
      • C.2.3.11Use Cloud first
        • C.2.3.11.1Enforce this order of preference: Software as a Service (SaaS) first, then Platform as a Service (PaaS), and lastly Infrastructure as a Service (IaaS)
        • C.2.3.11.2Enforce this order of preference: Public cloud first, then Hybrid cloud, then Private cloud, and lastly non-cloud (on-premises) solutions
        • C.2.3.11.3Design for cloud mobility and develop an exit strategy to avoid vendor lock-in
      • C.2.3.12Design for Performance, Availability, and Scalability
        • C.2.3.12.1Design for resiliency
        • C.2.3.12.2Ensure response times meet user needs for availability
        • C.2.3.12.3Support zero-downtime deployments for planned and unplanned maintenance
        • C.2.3.12.4Use distributed architectures, assume failure will happen, handle errors gracefully, and monitor actively
    • Security Architecture and Privacy
      
      • C.2.3.13Design for Security and Privacy
        • C.2.3.13.1Implement security across all architectural layers
        • C.2.3.13.2Categorize data properly to determine appropriate safeguards
        • C.2.3.13.3Perform a privacy impact assessment (PIA) and mitigate all privacy risks when personal information is involved
        • C.2.3.13.4Balance user and business needs with proportionate security measures and adequate privacy protections.

• D.1 Effective date
  
  • D.1.1These procedures take effect on December 1, 2018.
• D.2 Procedures
  
  • D.2.1This procedures provide details on the requirements set out in section 6 of the Directive on Management of Information Technology.
  • D.2.2Mandatory procedures are as follows:
    • D.2.2.1Follow the Government of Canada Digital Standards – APIs must be developed following the Government of Canada's Digital Standards, specifically :
      • D.2.2.1.1Design with users by:
        • D.2.2.1.1.1Working with the developers who are expected to consume your API to ensure the interface specification meets their needs and addresses any constraints or limitations they may have.
        • D.2.2.1.1.2Building APIs against the business requirements consuming systems are intended to support and not the backend data structures they're accessing.
      • D.2.2.1.2Empower staff to deliver better services by:
        • D.2.2.1.2.1Ensuring the necessary tooling, training, and processes are in place to support a robust and agile API development and lifecycle management process.
        • D.2.2.1.2.2Adopt Continuous Integration and Delivery (CI/CD) and Test Driven Development (TDD) practices supported by automation tools and integrated security testing. This provides the basis for DevOps adoption as maturity improves.
      • D.2.2.1.3Work in the open by default by:
        • D.2.2.1.3.1Building APIs which can be publically consumed and allow reuse when working with non-sensitive data.
      • D.2.2.1.4Use open standards and solutions by:
        • D.2.2.1.4.1Exposing APIs using industry accepted open standards, while vendor proprietary protocols and data schemas must be avoided.
        • D.2.2.1.4.2Leveraging open source tools and frameworks to implement the API where possible.
      • D.2.2.1.5Iterate and improve frequently by:
        • D.2.2.1.5.1Design APIs with reuse in mind, but don't anticipate or guess at future requirements.
        • D.2.2.1.5.2Ensure APIs are designed in such a way as to enable iterations as new requirements and use cases emerge, while providing a reasonable level of backwards compatibility.
    • D.2.2.2Build APIs following the RESTful model by default. Representational State Transfer (REST) is effectively the standard for integration with cloud services and is also the standard set by the majority of other Governments with mature API programs. Follow industry best practices when designing and developing your RESTful API by:
      • D.2.2.2.1Represent resources as Uniform Resource Locators (URLs) by ensuring URLs represent entities and business objects, not operations on those entities and objects (i.e., avoid verbs inside the URL string).
      • D.2.2.2.2Use JavaScript Object Notation (JSON) and other JSON-based representations (e.g., JSON-LD) as the message structure wherever possible and apply the following practices:
        • D.2.2.2.2.1Form responses as a JSON object and not an array. Arrays can limit the ability to include metadata about results and limit the APIs ability to add additional top-level keys in the future.
        • D.2.2.2.2.1Avoid unpredictable (i.e., dynamic) object keys such as those derived from data as this adds friction for clients.
        • D.2.2.2.2.3Select a single grammar case for object keys, such as "underscore" or "CamelCase" and use it consistently.
      • D.2.2.2.3Ensure each verb represents a single operation on a given resource and avoid using request parameters to pass additional operations. However, the following are appropriate uses of HyperText Transfer Protocol (HTTP) verbs in the context of a RESTful API:

        GET (retrieve or query a resource),

        POST (create a new resource or initiate an action),

        PUT (update or replaced an existing resource), and

        DELETE (remove a resource)

      • D.2.2.2.4Use Uniform Resource Identifiers (URIs) to uniquely identify data that is returned as a part of a response so future operations can be performed on it, and iterations can leverage existing resources with minimal rework.
      • D.2.2.2.5Content negotiation must be done using the agent-driven approach via HTTP headers, including:
        • D.2.2.2.5.1ACCEPT and CONTENT-TYPE request headers are mandatory
        • D.2.2.2.5.2AUTHORIZATION header is mandatory for secured APIs
        • D.2.2.2.5.3The API Key must be passed in the header rather than the URI
        • D.2.2.2.5.4API keys/tokens must be securely setup and used appropriately
        • D.2.2.2.5.5The response must contain the CONTENT-TYPE header.
      • D.2.2.2.5.6Publish using Simple Object Access Protocol (SOAP)/Extensible Markup Language (XML) APIs only if there are technical constraints on either the provider or consumer sides. All SOAP endpoints should follow SOAP 1.2 specifications and be WS-I Basic Profile 2.0 compliant.
    • D.2.2.3Ensure APIs respond with message schemas that are well-defined, easy to understand, and consume by applying the following practices:
      • D.2.2.3.1Leveraging industry recognized common information models (e.g., NIEM, HR-JSON, HL7) where possible. If you have to define your own information model, create a model which is technology and platform agnostic rather than simply reusing a vendor proprietary schema. The appropriate use of common information models must follow Government of Canada Data Standards.
      • D.2.2.3.2Exposing raw data structures (e.g., rowsets, table arrays, LDAP DN) from backend systems must be limited to open data, reporting, and statistical APIs only, and strictly prohibited on master data, transactional, or business APIs. APIs should abstract backend physical data representation from the consumer.
      • D.2.2.3.3Avoiding relational data structures such as JSON and XML as they are hierarchical data structures and are not well suited to representing relational data. Relational data schemas should be flattened based on the perspective of the API consumer.
      • D.2.2.3.4Ensuring the constraints of a data schema are apparent when reading the schema definition. Generic data structures such as key-value pairs and generic fields are prohibited due to the inability to test API compatibility at the contract level.
      • D.2.2.3.5Avoiding building custom error codes and schemes which require heavy parsing by the consuming system. Conform to HTTP status codes when building RESTful APIs and conform to SOAP 1.2 faults when building SOAP APIs.
      • D.2.2.3.6Abstracting internal technical details whereby responses, including error messages, should abstract technical details which the API consumer has no visibility into. Internal technical errors, thread dumps, and process identifiers etc. must all be kept out of response data.
      • D.2.2.3.7Ensuring the interaction between the API consumer and provider is stateless. APIs must not expect any concept of session or management of state on the part of the consumer (e.g., passing session IDs). Any interactions where multiple APIs are called in a repeatable sequence to create a singular business interaction should be implemented as a composite API to avoid the burden of consumer-side orchestration.
    • D.2.2.4Validate your API design by consuming it with a production application within your organization.
      • D.2.2.4.1Build once for multiple channels by designing APIs so they can be consumed by internal Government of Canada systems, trusted partners, and external parties (i.e., public). Design should allow for different data access profiles to be applied, either to the API or at a proxy layer, without the need to build additional APIs.
      • D.2.2.4.2Pilot internally first by building APIs in parallel with an internal use case which would integrate with the API and use this internal pilot to validate the API implementation before publishing it for external use.
    • D.2.2.5Ensuring the security of the API when designing and implementing any API which provides access to protected or privileged data. As a baseline minimum, the following security control practices must be followed for any API other than those exposing public data (e.g., open data):
      • D.2.2.5.1Enforce secure communications by ensuring that sensitive data is never sent over an insecure or unencrypted connection, and where possible non-sensitive data should also be sent over a secure connection. Enable TLS 1.2 or subsequent versions, in accordance with CSE guidance.
      • D.2.2.5.2Design APIs to be resistant to attacks by ensuring that all APIs are designed and implemented to be resistant to common API attacks such as buffer overflows and SQL injection. Treat all submitted data as untrusted and validate before processing. Leverage schema and data models for ensuring correct data validation.
      • D.2.2.5.3Do not include sensitive data in request URLs as request URL strings can be tracked and compromised even with transport encryption. If a query involves sensitive data elements (e.g., SIN), pass the query parameters as a JSON message payload rather than in the URL request string.
      • D.2.2.5.4Protect access to APIs by implementing an access control scheme that protects APIs from being improperly invoked, including unauthorized function and data references. Always authenticate and authorize before any operation to ensure access to APIs are restricted to permitted individuals and/or systems. Use open standards such as OpenID Connect and Open Authorization 2.0 (OAuth 2.0) for RESTful APIs, and Security Assertion Markup Language 2.0 (SAML 2.0) for SOAP APIs. Ensure that the API key/secret is adequately protected. Open data APIs must be secured with an API key to allow for usage tracking and provide the ability to identify and prevent potential malicious use. Open data APIs must be secured with an API key to allow for usage tracking and provide the ability to identify and prevent potential malicious use.
      • D.2.2.5.5Apply secure token management practices whereby token-based authentication is strongly recommended and is mandatory for any APIs published to be consumed across the Government of Canada and/or externally. Use industry standard tokens; do not create custom tokens; and avoid using vendor proprietary token schemes. JSON Web Token (JWT) is required for RESTful API interactions. WS-Security SAML Token Profile is required for SOAP APIs. All access tokens must expire within a reasonable amount of time (i.e., less than 24 hours). In the case of SAML, the assertion expiry must be set to control the validity period of the entire authentication and authorization session.
      • D.2.2.5.6Use gateways and proxies instead of whitelists when exposing APIs to the internet. Use a secure gateway layer to provide a security control point instead of simply whitelisting inbound Internet Protocol addresses (IPs). The API Store's gateway functionality may be used. When consuming external APIs, route flows through a forward (egress) proxy instead of using IP address whitelisting on the outbound firewall.
      • D.2.2.5.7Integrate and automate security testing to validate any new changes to API source code and to ensure robustness of requested changes. Assess the change impact and conduct testing accordingly. Periodic audits of API access may be required depending on the nature of the data and its usage.
      • D.2.2.5.8Audit access to sensitive data whereby access to APIs dealing with sensitive and/or personal data must be logged for future audit and reviewed on a regular basis. Access logs must include as a minimum both the system and individual identifiers attempting to access the API along with the timestamp.
      • D.2.2.5.9Log and monitor for performance and activity by tracking usage and monitoring for suspicious activity including abnormal access patterns such as after-hours requests, large data requests, etc. Use logging standards (e.g. common event format) and integrate logs centrally. Identify dependencies and monitor for vulnerabilities, especially those for uploaded run-times that work as part of the API. Suspicious events must be sent to the appropriate security operations capability or authority in compliance with Government of Canada Cyber Security policies and Government of Canada Cyber Security Event Management Plan.
    • D.2.2.6Use consistent encoding and meta-data to ensure APIs are interoperable across organizations and maintain data consistency by implementing the following practices when defining the API:
      • D.2.2.6.1Use Unicode Transformation Format-8 (UTF-8) as the standard encoding type for all text and textual representations of data through APIs. It must be adhered to for all APIs published across the GC and externally. Other encodings may be used for single purpose and/or intra-organizational APIs if and only if there are technical limitations to using UTF-8.
      • D.2.2.6.2Use consistent date-time format by International Organization for Standardization 8601 (ISO 8601), in Coordinated Universal Time (UTC), as the standard date-time format for data and timestamp fields in APIs published across the GC and externally. The date format is <yyyy-mm-dd> while timestamp format is <yyyy-mm-dd>T<hh:mm:ss>Z. Any other representation of time in the source system must be converted to this format by the API.
      • D.2.2.6.3Support official languages whereby all English or French content returned as data are to be nested with BCP-47 language codes used as keys, specifically "en" and "fr". External facing APIs must reply with content in the requested language if the backend data support it. APIs must interpret the ACCEPT-LANGUAGE HTTP header and return the appropriate content. If the header is not set, then content in both languages should be returned. In the case of unilingual data and systems, every effort should be made to ensure that the language is appropriately indicated in the response message.
    • D.2.2.7Evolve and support the API throughout its lifecycle by practicing the following:
      • D.2.2.7.1Build iteratively by releasing new versions of the API as requirements change and/or new requirements are introduced. Actively solicit feedback from the API consumers to understand whether the API is providing appropriate value and make adjustments in future iterations.
        • D.2.2.7.1.1Version each and every change to the API no matter how small, following the v<Major>.<Minor>.<Patch> versioning structure whereby:
          • Major = Significant release which is likely to break backwards compatibility
          • Minor = Addition of optional attributes or new functionality that is backwards compatible, but should be tested
          • Patch = Internal fix which should not impact the schema and/or contract of the API

          For example, going from v1.1.0 to v1.1.1 would allow a simple deploy-in-place upgrade as it is a patch, while going from v1.1.0 to v2.0.0 would be a major release and would require the legacy version to be kept while consumers test and migrate to the new version.

        • D.2.2.7.1.2The URL must reflect only the major version (e.g., v3). Versions must not be passed as a parameter or in the request header to force the API consumer to explicitly identify the version and to avoid defaulting to an incompatible version. Minor and patch versions do not need to be in the URL as they should not break backwards compatibility, but they should be clearly identified in the contract, interface documentation, and response message.
      • D.2.2.7.2Respect existing consumer dependencies by supporting at least one previous major version (i.e., N-1) to ensure consuming systems have time to migrate to the latest version of the API. Communicate your development roadmap with consuming teams and work with them to understand the impact of any major changes. Set clear deprecation policies and timelines up front so consumers understand how long they have to migrate to each new release before the legacy one is placed offline. Coordinate any necessary testing on all minor and major releases.
      • D.2.2.7.3Publish a designated point of contact to any teams consuming your API to the API Store. If the API is published for GC-wide or external use, publish a support email account. A phone number should also be provided for high-criticality APIs.
      • D.2.2.7.4Each API should be accompanied with a clearly defined Service Level Agreement (SLA). At a minimum, the SLA should define the following:
        • Support hours (e.g., 24/7, 9/5, coast to coast business hours)
        • Service availability (e.g., 99%)
        • Support response time (e.g., within the hour, 24 hours, best effort)
        • Scheduled outages (e.g., nightly, weekly, every 2nd Sunday evening)
        • Throughput limit (e.g., 100 requests per second per consumer)
        • Message size limit (e.g., <1Mb per request)
    • D.2.2.8Measure and publish API benchmarks whereby API performance should be benchmarked periodically to ensure the performance and capacity continually meets existing and projected business needs. The following actions should be taken:
      • D.2.2.8.1Run performance and load tests against the API to determine the response time and throughput during reasonable load as well as identify performance thresholds beyond which the API becomes unstable. Performance tests should be integrated into the development cycle, preferably through an automated continuous integration and continuous deployment (CI/CD) pipeline to ensure they're done on each new release.
      • D.2.2.8.2Performance summaries (e.g., average response time and associated throughput, max stable throughput) should be published alongside the API contract and SLA. This should be updated on every release.
      • D.2.2.8.3Runtime performance should be monitored and reported on to identify trends and to ensure the API has appropriate amount of capacity to meet usage demand.
      • D.2.2.8.4Throttling mechanisms should be implemented to control throughput against the stated SLA to guard against unexpected spikes in activity. It is better to reject requests that exceed the pre-defined throughput limits than to let the API crash.
    • D.2.2.9Use and design APIs sensibly by recognizing that APIs are not the solution for all integration scenarios. The following considerations should be made when deciding to implement an API as well as designing what types of queries are allowed to ensure the integration architecture is appropriate and sustainable:
      • D.2.2.9.1Query-based APIs (pull pattern) are preferred over data sink APIs (push pattern). Having consuming systems query APIs based on specific parameters ensures that only data that's required in the context of a business process or transaction is being passed. This approach also ensures that data access can be more finely controlled from a security perspective. Data sink APIs promote mass data synchronization and proliferation, which is antithesis to what an API-centric architecture is intended for. Bulk data integration techniques and tools should be used for data synchronization patterns and only when absolutely necessary.
      • D.2.2.9.2Restrict the use of wildcard queries in APIs as they can be dangerous from a data performance perspective. If wildcard characters are allowed, ensure there are restrictions on which and how many parameters can have wildcard input to prevent large data query sizes. It is much safer to reject a query with too many wildcards than to timeout on a database query on the backend.
      • D.2.2.9.3APIs exposing large datasets must support some form of data segmentation. The following are some common patterns for pagination along with appropriate use cases:
        • page and per_page – Best used to navigate large static datasets (e.g., reference data) where the same set of data is likely to be returned given the same page reference over time.
        • offset and limit – Best used for APIs fronting Structured Query Language (SQL)-based backends where the offset represents the data cursor on a given indexed column.
        • since and limit – Best used for queries where the consumer is interested in the delta since the last query and the backend data structure is indexed based on time.
      • D.2.2.9.4The ability to inject consumer defined query strings or objects into an API must be limited to open data, reporting, and statistical APIs only, and strictly prohibited on master data, transactional or business APIs. Dynamic and open queries create dangerous attack surfaces for APIs. It's better to invest more effort in identifying all the valid query use cases and design the API to specifically meet them. GraphQL can be used for statistical, analytics, and reporting purposes, but should not be used to support business transactions. OData should only be used if there are technical limitations by the backend system and only for an organization's internal APIs.
      • D.2.2.9.5Apply special considerations for bulk datasets as there will be scenarios where APIs will need to be involved in making bulk datasets available between systems or to the public. In those scenarios, apply the following considerations:
        • D.2.2.9.5.1Smaller datasets should be returned in low overhead formats (e.g., Comma-separated values (CSV) or JSON) rather than XML. The use of compressed file attachments should be avoided, especially when consuming external APIs as they may bypass malicious content scanning mechanisms.
        • D.2.2.9.5.2An API may be implemented as a trigger to initiate an out-of-band interface (e.g., managed file transfer) more appropriate for moving large data volumes.
        • D.2.2.9.5.3If the dataset is published on file servers already available to the consumer, an API could be implemented to return a link to a specific file based on specific request parameters.
    • D.2.2.10APIs must be published to be discoverable. How each API is to be consumed must be clearly documented. The documentation must be concise and up to date. The following practices must be adhered to in order to ensure APIs are documented appropriately without incurring the excess burden of managing companion documentation:
      • D.2.2.10.1All APIs should be published to the API Store for the purposes of discovery and lifecycle management. APIs must be appropriately tagged to indicate whether they are for intra-departmental, Government of Canada internal, or public consumption.
      • D.2.2.10.2Use OpenAPI, a machine-readable interface specification for RESTful APIs, to document RESTful API contracts. There are open source tools (e.g., Swagger) which can then generate human-readable documentation from this specification which avoids the need to create and maintain separate documentation.
      • D.2.2.10.3Each SOAP API must be accompanied with a Web Services Description Language (WSDL) contract. The WSDL is a machine-readable specification which allows the API consumer developer to generate the consumer code.
      • D.2.2.10.4Publish unit tests and test data as the most effective way to document what an API is supposed to do alongside the API contract. This becomes easier if Test-Driven-Development (TDD) methodology was followed in the development of the API.
      • D.2.2.10.5Avoid heavy companion documents. The need for a large separate document explaining each method and attribute is usually an indication that the API is too large, generic, or complex. Consider breaking the API down into smaller components and making the message structure more constrained.