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

This page has been archived on the Web

Information identified as archived is provided for reference, research or recordkeeping purposes. It is not subject to the Government of Canada Web Standards and has not been altered or updated since it was archived. Please contact us to request a format other than those available.

Note to reader

The Directive on Management of Information Technology is no longer in effect. It was replaced by the Directive on Service and Digital and the Policy on Service and Digital on April 1, 2020.

1. Effective date

This directive takes effect on April 1, 2009, and incorporates changes effective as of December 4, 2018.

2. Application

2.1 This directive applies to all departments as defined in section 2 of the Financial Administration Act (FAA), unless excluded by specific acts, regulations or Orders in Council.

2.2 Sections 6.2.2 and 7.1 of this directive do not apply to the Office of the Auditor General, the Office of the Privacy Commissioner, the Office of the Information Commissioner, the Office of the Chief Electoral Officer, the Office of the Commissioner of Lobbying, the Office of the Commissioner of Official Languages and the Office of the Public Sector Integrity Commissioner. In these organizations, deputy heads are solely responsible for monitoring and ensuring compliance with this directive and for responding to cases of non-compliance in accordance with any Treasury Board instruments providing principles and guidance on the management of compliance.

3. Context

3.1 Information technology (IT) enables the federal government to effect operations and service transformation. IT is strategically critical to increasing government productivity and enhancing government services to the public for the benefit of citizens, businesses, taxpayers and employees. This directive provides essential support for the management of IT in the areas of IT governance, IT planning and IT strategy.

3.2 The federal government invests a significant portion of its annual budget on information technology and supporting infrastructure. Rapidly developing technology, incompatible business practices and the fragmented approach to IT investments undermine effective and efficient delivery of government programs and services. Multiple data centres and networks also pose significant security risks. A more strategic approach to IT investments is needed to ensure interoperability of departmental systems and compatible business practices.

3.3 This directive supports the Policy on Management of Information Technology by providing departmental chief information officers (CIO) or equivalents or other officials supporting the management of IT with additional requirements to ensure consistency in IT management processes.

3.4 This directive is to be read in conjunction with the Policy Framework for Information and Technology, the Policy on Management of Information Technology and the Policy on Information Management. The directive is also related to the Policy on Investment Planning – Assets and Acquired Services and the Policy on the Management of Projects. The departmental IT plan is a component of the broader departmental investment plan that has a five-year horizon (as required under the Policy on Investment Planning – Assets and Acquired Services). To keep up with the pace of technological changes, however, the departmental CIO or equivalent reviews the departmental IT plan annually and updates it, as required, at the time of the review. The departmental IT plan covers the strategic, tactical and operational aspects of the management of IT.

3.5 Additional requirements for IT governance, IT planning and IT strategy will be set out in the standards. The Chief Information Officer Branch (CIOB) of the Treasury Board Secretariat (TBS) will also publish guidelines and tools to assist departments if required.

3.6 The Treasury Board has delegated authority to the Secretary of the Treasury Board to issue this directive and to make administrative and technical changes.

3.7 The Secretary of the Treasury Board has sub-delegated authority to the Chief Information Officer of Canada to issue this directive and to make administrative and technical changes.

4. Definitions

4.1 Definitions to be used in the interpretation of this directive are attached in Appendix A.

5. Directive statement

5.1 Objectives

The objectives of this directive are to:

5.1.1 Ensure efficient and effective use of information technology to support federal government priorities, program delivery, increased innovation, productivity and enhanced services to the public; and

5.1.2 Support the management of IT on a government-wide basis by providing more robust and mature management practices to reduce duplication, enable the adoption of alternate service delivery models, including common and shared services, promote alignment and interoperability and optimize service delivery.

5.2 Expected results

The expected results of this directive are the following:

5.2.1 Stakeholders will exercise their roles and responsibilities in the management of IT more effectively by participating in designated governance, advisory and working group forums;

5.2.2 Efficiency and effectiveness in IT management will increase along with better decision making at all levels, thus ensuring that IT supports program delivery and provides value for money;

5.2.3 The use of common or shared IT assets and services by departments will increase and ensure efficiency gains;

5.2.4 IT will enable more innovative and responsive services; and

5.2.5 The consistency of security practices will improve as a result of the increased consolidation of systems and services.

6. Requirements

6.1 Departmental CIO or equivalent

The departmental CIO or equivalent is responsible for the following:

6.1.1 IT governance

  • Developing, for deputy head approval, departmental governance structures to support effective IT decision making;
  • Coordinating, promoting and directing IT and collaborating on IT-enabled business transformation with the business owner and other stakeholders;
  • Participating in federal government IT governance forums, including the Chief Information Officer Council (CIOC) and other designated governance and advisory forums, related to IT and federal government IT architecture matters;
  • Balancing individual departmental interests with government-wide interests and aligning IT to government-wide directions and strategies;
  • Advising the CIOC on the decisions, plans, strategies, directions, progress, risks and challenges related to the initiatives that affect the provision or use of IT services in or across departments;
  • Monitoring and measuring departmental IT management performance using both government-wide and departmental key performance indicators as appropriate; and
  • Advising the deputy head, as well as the business owner and other stakeholders, of the effect of new or amended legislation and policies on departmental IT plans.
  • Submitting to the Government of Canada Enterprise Architecture Review Board proposals concerned with the design, development, installation and implementation of digital services or solutions, information systems, and applications (”digital initiatives”):
    • where the department is willing to invest a minimum of the following amounts in order to address the problem or take advantage of the opportunity:
      • $2.5 million dollars for departments without an approved Organizational Project Management Capacity Class or with an approved Organizational Project Management Capacity Class of 1;
      • $5 million dollars for departments with an approved Organizational Project Management Capacity Class of 2;
      • $10 million dollars for departments with an approved Organizational Project Management Capacity Class of 3;
      • $15 million dollars for the Department of National Defence;
      • $25 million dollars for departments with an approved Organizational Project Management Capacity Class of 4;
    • That involve emerging technologies;
    • That require an exception to any applicable Directive or Standard under the Policy on the Management of Information Technology;
    • That are categorized at the protected B level or below‎ using a deployment model other than public cloud for application hosting (including infrastructure), application deployment, or application development; or,
    • As directed by the Chief Information Officer of Canada.
  • Ensuring that all proposals submitted to the Government of Canada Enterprise Architecture Review Board have first been assessed by the departmental architecture review board where one has been established;
  • Ensuring that proposals to the Government of Canada Enterprise Architecture Review Board are submitted following review of concept cases for IT-enabled Projects as per the Mandatory Procedures for Concept Cases for IT-enabled Projects, and before the development of a Treasury Board Submission or Departmental Business Case;
  • In carrying out responsibilities under 6.2.10 of the Policy on Management of Information Technology, ensuring all departmental initiatives are assessed against and meet the requirements of Appendix C: Mandatory Procedures for Enterprise Architecture Assessment and Appendix D: Mandatory Procedures for Application Programming Interfaces.

6.1.2 IT planning

  • Developing, implementing and sustaining an effective departmental IT planning process that is integrated with the overall departmental corporate planning process and aligned with the investment planning process to support business, enable transformation and guide IT decision making;
  • Preparing an IT plan and an IT progress report against the plan as established in Appendix B and submitting it to TBS (CIOB) as requested; and
  • Ensuring that the IT plan is aligned to support both departmental business and government-wide strategic directions by communicating with and engaging departmental and external stakeholders, as appropriate.

6.1.3 IT strategies

  • Developing and maintaining efficient and effective departmental IT management practices and processes, as informed by ITIL (Information Technology Infrastructure Library) and COBIT (Control Objectives for Information and related Technology), with priority on IT asset management, the IT service catalogue and IT service costing and pricing, as appropriate;
  • Aligning departmental IT management practices, processes and technology architecture with federal government strategy, directions, standards and guidelines as they become available and as they evolve under the guidance of the CIOC;
  • Participating, as a service provider or a service user, in the conception, planning, evolution and oversight of common or shared IT services and solutions;
  • Developing, implementing and sustaining departmental strategies for producing or using appropriate common or shared IT services and solutions, based on the IT plans;
  • Aligning and documenting IT services, whether planned or currently offered to recipients, according to the Policy on Management, Resources and Results Structure (MRRS). The Profile of GC Information Technology Services provides additional guidance for the alignment and documentation of IT services; and
  • Reviewing and assessing IT services periodically to identify opportunities for enhancing efficiency, effectiveness and innovation as determined by governance and in collaboration with service providers, service users and other stakeholders.

6.2 Monitoring and reporting requirements

6.2.1 Within departments

6.2.2 Government-wide

  • TBS (CIOB) will monitor compliance with this directive through the MAF assessment process, examination of Treasury Board submissions, DPRs, and requested departmental evaluations and studies.
  • TBS (CIOB) will review this directive and its effectiveness at the five-year mark of implementation. When substantiated by risk analysis, TBS (CIOB) will also ensure that an evaluation of this directive is conducted.

7. Consequences

7.1 Consequences of non-compliance can include an informal follow-up or request for information from TBS, such as an external audit or report on corrective measures.

8. Roles and responsibilities of government organizations

Note: This section identifies other departments that have a role in IT management. In and of itself, the section does not confer authority.

8.1 TBS (CIOB), in consultation with other departments, is responsible for the following:

8.1.1 Developing policy instruments, including frameworks, policies, directives, standards, guidelines and tools, and providing interpretive advice and guidance on these instruments;

8.1.2 Setting government-wide strategic directions for IT, including areas of IT that offer significant government-wide benefits or enable government to take the lead in achieving these benefits;

8.1.3 Coordinating implementation of government-wide IT strategic directions;

8.1.4 Communicating and engaging the government-wide IT community on plans, progress, risks and challenges associated with the management of IT in the federal government;

8.1.5 Developing competency and other professional standards for the federal government's IT specialists as required; and

8.1.6 Providing support to the CIOC and other committees and working groups, as necessary, to address government-wide strategic IT directions and issues.

8.2 The Department of Public Works and Government Services (PWGSC) is a key provider of a number of common and shared IT infrastructure products and services to departments. PWGSC is responsible for establishing governance for the delivery of its services to client departments.

8.3 The Office of the Chief Human Resources Officer (OCHRO), TBS is responsible for providing advice and guidance to stakeholders on a full range of sound human resources (HR) management strategies, including integrated business and HR planning. OCHRO representatives are available to advise TBS (CIOB) on recruitment and retention strategies and to share lessons learned.

8.4 The Canada School of Public Service is responsible for the development and delivery of a government-wide core learning strategy and program – consistent with the Policy on Learning, Training and Development and based on consultation with the relevant functional authority centres for all public service employees involved in IT management.

9. References

10. Enquiries

Please address enquiries about this directive to the departmental CIO or equivalent. For assistance in interpreting this directive, the departmental CIO or equivalent should contact:

Chief Information Officer Branch
Treasury Board Secretariat
Ottawa ON  K1A 0R5
Telephone: 613-946-5029
Fax: 613-946-4334

Appendix A - Definitions

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).
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.
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.

Appendix B - Content of IT plan and IT progress report

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.

Appendix C - Mandatory Procedures for Enterprise Architecture Assessment

  • 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. program services as business capabilities to establish a common vocabulary between business, development, and operation
          • C. capabilities that are common to the GC enterprise and can be shared and reused
          • C. 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. on the needs of users, using agile, iterative, and user-centred methods
          • C. to both accessibility and official languages requirements
          • C. all skillsets required for delivery, including for requirements, design, development, and operations
          • C. across the entire application lifecycle, from development and testing to deployment and operations
          • C. quality is considered throughout the Software Development Lifecycle
          • C. accountability for privacy is clear
          • C. 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. performance expectations for each IT service
          • C. an audit trail available for all transactions to ensure accountability and non repudiation
          • C. business and IT metrics to enable business outcomes
          • C. oversight and lifecycle management to digital investments through governance
      • Information Architecture
        • C.2.3.4Data Collection
          • C. data is collected in a manner that maximizes use and availability of data
          • C. data collected aligns to existing enterprise and international standards
          • C. enterprise or international standards don't exist, develop Standards in the open with key subject matter experts
          • C. collection of data yields high quality data as per data quality guidelines
          • C. data is collected through ethical practices supporting appropriate citizen and business-centric use
          • C. should only be purchased once and should align with international standards
          • C. necessary, ensure collaboration with department/ agency data stewards/ custodians, other levels of government, and Indigenous people
        • C.2.3.5Data Management
          • C. alignment with enterprise and departmental data governance and strategies
          • C. accountability for data roles and responsibilities
          • C. to maximize data use and availability
        • C.2.3.6Data Storage
          • C. data is stored in a secure manner in accordance with the National Cyber Security Strategy, and the Privacy Act
          • C. existing retention and disposition schedules
          • C. data is stored in a way to facilitate easy data discoverability, accessibility, and interoperability
        • C.2.3.7Data Sharing
          • C. should be shared openly by default as per the Directive on Open Government
          • C. government-held data can be combined with data from other sources enabling interoperability and interpretability through for internal and external use
          • C. the collection of redundant data
          • C. existing data where possible
          • C. data sharing and collaboration
      • Application Architecture
        • C.2.3.8Use Open Standards and Solutions by Default
          • C. possible, use open standards and open source software first
          • C. 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. 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. source code must be released under an appropriate open source software license
          • C. public data to implement Open Data and Open Information initiatives
        • C.2.3.9Maximize Reuse
          • C. and reuse existing solutions, components, and processes
          • C. enterprise and cluster solutions over department-specific solutions
          • C. simplification by minimizing duplication of components and adhering to relevant standards
          • C. the GC EARB about departmental investments and innovations
          • C. code publicly when appropriate, and when not, share within the Government of Canada
        • C.2.3.10Enable Interoperability
          • C. all functionality as services
          • C. microservices built around business capabilities. Scope each service to a single purpose
          • C. 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. applications in containers
          • C. 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. this order of preference: Software as a Service (SaaS) first, then Platform as a Service (PaaS), and lastly Infrastructure as a Service (IaaS)
          • C. this order of preference: Public cloud first, then Hybrid cloud, then Private cloud, and lastly non-cloud (on-premises) solutions
          • C. for cloud mobility and develop an exit strategy to avoid vendor lock-in
        • C.2.3.12Design for Performance, Availability, and Scalability
          • C. for resiliency
          • C. response times meet user needs for availability
          • C. zero-downtime deployments for planned and unplanned maintenance
          • C. 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. security across all architectural layers
          • C. data properly to determine appropriate safeguards
          • C. a privacy impact assessment (PIA) and mitigate all privacy risks when personal information is involved
          • C. user and business needs with proportionate security measures and adequate privacy protections.

Appendix D - Mandatory Procedures for Application Programming Interfaces

  • 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. with users by:
          • D. 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. APIs against the business requirements consuming systems are intended to support and not the backend data structures they're accessing.
        • D. staff to deliver better services by:
          • D. the necessary tooling, training, and processes are in place to support a robust and agile API development and lifecycle management process.
          • D. 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. in the open by default by:
          • D. APIs which can be publically consumed and allow reuse when working with non-sensitive data.
        • D. open standards and solutions by:
          • D. APIs using industry accepted open standards, while vendor proprietary protocols and data schemas must be avoided.
          • D. open source tools and frameworks to implement the API where possible.
        • D. and improve frequently by:
          • D. APIs with reuse in mind, but don't anticipate or guess at future requirements.
          • D. 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. 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. 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. 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. unpredictable (i.e., dynamic) object keys such as those derived from data as this adds friction for clients.
          • D. a single grammar case for object keys, such as "underscore" or "CamelCase" and use it consistently.
        • D. 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. 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. negotiation must be done using the agent-driven approach via HTTP headers, including:
          • D. and CONTENT-TYPE request headers are mandatory
          • D. header is mandatory for secured APIs
          • D. API Key must be passed in the header rather than the URI
          • D. keys/tokens must be securely setup and used appropriately
          • D. response must contain the CONTENT-TYPE header.
        • D. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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.

© Her Majesty the Queen in Right of Canada, represented by the President of the Treasury Board, 2017,
ISBN: 978-0-660-09658-2