├── API-Guidelines.md ├── CONTRIBUTING-FR.md ├── CONTRIBUTING.md ├── LICENCE-FR.md ├── LICENSE.md ├── Lignes-directrices-sur-les-API.md ├── README-FR.md └── README.md /API-Guidelines.md: -------------------------------------------------------------------------------- 1 | # Building connected digital services: API Guidelines 2 | 3 | ## Introduction 4 | 5 | ### About this guide 6 | This guide is for anyone working to develop digital services for a public service, whether as part of the Ontario Public Service, a government agency, or beyond. 7 | 8 | These guidelines are meant to be a roadmap, not a roadblock. They aim to help streamline digital service development for a more consistent and robust product for both developers and end users. 9 | 10 | ### What APIs can do 11 | Application Programming Interfaces (APIs) let applications talk to each other in structured ways. Software developers create APIs to share some functionality or data from an application they've developed with anyone who might want to work with it. 12 | 13 | For example, when you look at the weather app on your phone, the information you see is coming from an API built by your local weather service. Their API takes weather prediction data and converts it into a format that other app developers can use. This lets developers focus on building a user-friendly interface (for example, your phone's weather app) without having to worry about the science behind the data. 14 | 15 | APIs can do more than share data; they can be the connective tissue between multiple related but independent systems. An agency—such as the Ministry of Transportation Ontario—that issues driver's licenses could build an API that takes a license number and checks whether it has expired. This API would be very useful for a car rental company that wants to verify that a customer has a valid license. 16 | 17 | ### Why you should care about APIs 18 | APIs allow you to build reusable components and develop a platform, so that you don't have to reinvent the wheel every time. They are, in essence, the building blocks to a digital ecosystem. Understanding the value of APIs will help you shift your thinking into a digital first approach. 19 | 20 | Sharing data and processes through APIs: 21 | 22 | * reduces duplicated work 23 | * encourages communication and learning between teams 24 | * makes future application development more efficient 25 | 26 | Following this guide will help ensure that your services are: 27 | 28 | * interoperable with other platforms and services 29 | * less likely to be locked in to a particular vendor or technology 30 | * are more future proof and easier to update and test 31 | 32 | For teams in the Ontario Public Service, APIs also make it easier for agencies to meet Ontario's [Open Data Directive](https://www.ontario.ca/page/ontarios-open-data-directive), which requires all government data to be made public, unless it is specifically exempt. 33 | 34 | ### Who this guide is for 35 | You should read these guidelines if you are a: 36 | 37 | * **executives**, **directors** and **managers** looking to deliver interoperable digital services 38 | * **software developer** or **systems architect** looking for technical guidance 39 | * **product manager** on an API product who needs to understand the context 40 | * **business analyst** considering whether an API is a good solution for your problem 41 | * **policy advisor** on a digital service looking to better understand how APIs can help fulfill policy goals 42 | * **content designer**, **experience designer**, or a practitioner of any **other relevant discipline** who wants to familiarize themselves with the principles outlined here so they can add their perspective 43 | 44 | ### Standing on the shoulders of giants 45 | We've adapted these guidelines for the Ontario Public Service from the excellent work of other digital governments, including: 46 | 47 | * [Government of Canada](https://www.canada.ca/en/government/system/digital-government/modern-emerging-technologies/government-canada-standards-apis.html) 48 | * [UK Digital Service](https://www.gov.uk/guidance/gds-api-technical-and-data-standards) 49 | * [18F (the United States General Services Administration)](https://github.com/18F/api-standards) 50 | * [Government of New Zealand](https://snapshot.ict.govt.nz/guidance-and-resources/standards-compliance/api-standard-and-guidelines/index.html) 51 | * [Government of the State of Victoria, Australia](https://github.com/VictorianGovernment/api-design-standards) 52 | 53 | ## Business and process considerations 54 | If you are building an API for the Ontario Public Service, you must follow the Government of Ontario's [Digital Service Standard](https://www.ontario.ca/page/digital-service-standard) (DSS). Even if you're not in the OPS, we still encourage you to become familiar with the DSS, which outlines 14 key principles for building good, user-centered services. 55 | 56 | ### Consume what you build 57 | The best way to make sure your API design is good is to use it yourself within a production application. In the tech industry this is known as "eating your own dog food". 58 | 59 | Always try to build your APIs in parallel with an internal use case that will integrate with the API before you publish it for external use. The internal use case can serve as a low-profile pilot project that you can use to validate your assumptions about how to design the API, and will allow you to pivot and adjust your design as necessary. It also forces you to think from the perspective of the user and their needs. 60 | 61 | Make sure that the design of your API takes into account the different ways it might be used by your audience, including: 62 | 63 | * internal OPS systems 64 | * trusted partners 65 | * the public 66 | 67 | If you need to restrict an audience's access to certain components, build in user management capabilities instead of building multiple APIs. This approach will also highlight potential security issues from the beginning, when they can be addressed proactively. 68 | 69 | ### Talk to your users ([DSS #1](https://www.ontario.ca/page/digital-service-standard#section-1)) 70 | Work with the people who will be using the API to make sure that your architecture and design meet their needs. Engage user experience design experts to conduct research with: 71 | 72 | * technical users 73 | * business and program areas 74 | 75 | APIs should be built to meet specific business requirements to solve concrete problems. If you don't know what user need the API is meeting, or you are simply building the API to expose data without knowing what it'll be used for, that's a good sign that the API may not be the right solution. 76 | 77 | ### Use open standards ([DSS #9](https://www.ontario.ca/page/digital-service-standard#section-9)) 78 | Wherever possible, build your API using open source tools, frameworks and standards. The open source communities that develop these tools work through collaboration and consensus-building, and participants range from individual contributors working in their free time to large technology companies. The diversity of voices ensures that tools aim for interoperability, security, reliability and accessibility. Plus, because these tools aren't tied to a particular vendor or system, you're sure not to exclude users from outside the OPS. 79 | 80 | ### Iterate frequently ([DSS #8](https://www.ontario.ca/page/digital-service-standard#section-8)) 81 | The Ontario Digital Service Standard includes [an agile approach to development](https://www.ontario.ca/page/digital-service-standard#section-8). This means building your application in "iterations" that improve one set of features at a time so you can: 82 | 83 | * quickly test your service with real users 84 | * prove or disprove your assumptions 85 | * react faster to changing requirements, policy or technology 86 | 87 | The easier it is to iterate on your API, the easier it will be for other developers to use. 88 | 89 | ### Practice privacy by design ([DSS #10](https://www.ontario.ca/page/digital-service-standard#section-10)) 90 | While it's important to minimize barriers to access to government programs, it's also important to secure any sensitive data and minimize the potential for data breaches. 91 | 92 | Assess the data that will be shared through the API. When working with: 93 | 94 | * non-sensitive data, build APIs that can be publicly used with minimal barriers 95 | * sensitive data, put appropriate legal, privacy and security measures in place so data is not misused 96 | 97 | Refer to the [seven principles of privacy by design](https://www.ryerson.ca/pbdce/certification/seven-foundational-principles-of-privacy-by-design/) for more guidance. 98 | 99 | ### Broadcast your intentions ([DSS #5](https://www.ontario.ca/page/digital-service-standard#section-5)) 100 | Keep your users updated on your plans for the API. Work with them to understand the impact of any major planned changes. 101 | 102 | When releasing updates to an API that will break [backwards compatibility](#use-semantic-versioning) and require your developer partners to update their code, make sure to define and communicate clear deprecation timelines. This lets developers migrate to the new version before the old version they're using is taken offline, and avoids disrupting their work. 103 | 104 | Make sure that every API has at least one designated point of contact for the teams using it: 105 | 106 | * all APIs need a published support email account 107 | * high-criticality APIs also need a published phone number 108 | * ideally, publish a status page where users can find planned and unplanned outages and the latest information about the API's availability and status 109 | 110 | ### Make sure you actually need an API 111 | APIs are one of many ways to integrate data and functions between systems, but they are not always the best or only solution. If you need to archive a large amount of complex data relationships once a year, you might prefer a [bulk data transfer system](https://en.wikipedia.org/wiki/File_transfer). On the other hand, if the client application and the server are unlikely to be online at the same time and they need to communicate asynchronously, a [messaging queue](https://aws.amazon.com/message-queue/) might be a better solution. APIs are most useful if you're supporting real-time system interactions and data access. 112 | 113 | ## Technical considerations 114 | ### Design stateless APIs 115 | Every call to the API must contain all the information required to fulfill that request, without expecting the server to remember anything about any previous requests or contexts. This is known as stateless design. 116 | 117 | Do not store information about session states on the API server. Any sort of state management—for example, in the form of cookies or session IDs—must be maintained by the client sending the request. This makes it easier for your API to detect and recover from errors, as each error is contained within a single request and does not involve the entire state of the server. 118 | 119 | Stateless API design also improves the scalability of your server, since processing resources can be quickly freed up for each request, without needing to maintain a cache of incomplete transactions. 120 | 121 | ### Be RESTful if possible 122 | For the vast majority of use cases, we recommend [RESTful](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) API design. Representational State Transfer (REST) is the leading 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](https://restfulapi.net/) when designing and developing your RESTful API. In particular: 123 | 124 | #### Represent resources as URLs 125 | Each URL endpoint in a RESTful API design should represent an entity, resource, or business object. For example, a ServiceOntario (SO) API could provide endpoints to see information about a single SO location: 126 | 127 | * **DO**: `api.ontario.ca/offices/location/college-park` 128 | 129 | Do not use endpoints to perform operations on those entities or objects. This also means that your URL patterns should be composed of nouns, not verbs. 130 | 131 | * **DON'T**: `api.ontario.ca/getOpeningHours/college-park` 132 | 133 | #### Use URIs to identify resources 134 | If response data includes references to other resources in the API, include a full URL to the endpoint for that resource. This will allow the user to follow data references for future operations with minimal effort. 135 | 136 | If data is returned as a part of a response, use Uniform Resource Identifiers (URIs) to uniquely identify each data resource. This will allow the client or consuming system to directly refer to that data for future operations with minimal rework. 137 | 138 | For example, an endpoint that provides information about ServiceOntario locations close to a specific address should link directly to endpoints for each of those locations, instead of just listing the names. 139 | 140 | * **DO**: 141 | ``` 142 | { 143 | nearby: [{ 144 | name: "University Avenue", 145 | url: "api.ontario.ca/location/university-ave" 146 | }] 147 | } 148 | ``` 149 | 150 | * **DON'T**: 151 | ``` 152 | { 153 | nearby: ["University Avenue"] 154 | } 155 | ``` 156 | 157 | #### Return data as JSON 158 | Use JavaScript Object Notation ([JSON](https://www.json.org/)) and other JSON-based representations (such as [JSON-LD](https://json-ld.org/)) to transmit data between a client and a server. Responses that the API sends to the client should be formed as objects, and not as arrays or values. Arrays are not robust enough for including adequate metadata about the result object and can make it more difficult to iterate on the data design. 159 | 160 | For example, an endpoint that lists all ServiceOntario locations should include information about how many there are. 161 | 162 | * **DO:** 163 | ``` 164 | { 165 | total: 234 166 | locations: [ ... ] 167 | } 168 | ``` 169 | 170 | * **DONT:** 171 | ``` 172 | [ 173 | { id: university-ave ... }, 174 | { id: college-park ... } 175 | ] 176 | ``` 177 | 178 | Make sure the design of your data objects is predictable and easy to use. Follow a consistent grammar case for naming object keys, and do not use live data to create dynamic object keys. 179 | 180 | #### Do not overload HTTP request methods 181 | Each [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) (also known as an *HTTP verb*) should represent a *single* operation on a given resource or list of resources. Don't use request parameters to define additional operations; for example, don't use GET to do anything other than retrieving data. The following are idiomatic uses of HTTP verbs in the context of a RESTful API: 182 | 183 | * `GET` – get a resource 184 | * `POST` – create a new resource 185 | * `PUT` – update or replace an existing resource 186 | * `DELETE` – remove a resource 187 | 188 | You may also hear these referred to as `CRUD` (Create, Read, Update, Delete) operations. 189 | 190 | #### Use standard acceptance headers 191 | Any negotiation between the client and the server about what kind of data is being requested must be performed using [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). ACCEPT and CONTENT-TYPE request headers are mandatory, and AUTHORIZATION headers are mandatory for secured APIs. API keys must be passed in the header instead of in the request URL. 192 | 193 | If your API supports multiple languages, the ACCEPT-LANGUAGE header must be sent by the client, and the server must return content in the requested language. If a language header is not set for a multilingual system, content in all supported languages should be returned. Different languages should be nested under [BCP-47 language codes](https://tools.ietf.org/html/bcp47) (e.g. "en", "fr") as object keys. The returned response data must, at a minimum, contain the CONTENT-TYPE header. 194 | 195 | #### Use standardized error codes 196 | Use standard [ HTTP status codes](https://restfulapi.net/http-status-codes/) when building RESTful APIs. Conform to [ SOAP 1.2 faults](http://www.w3.org/TR/soap12-part1/#soapfault) when building SOAP APIs. Avoid building custom error codes and data schemes, which require more work by the client to parse. 197 | 198 | #### Alternatives to REST 199 | RESTful APIs will not be the best solution for every business problem, especially if there are technical constraints on either the provider or consumer sides. Here are some examples of alternative API architectures you can consider: 200 | 201 | ##### SOAP 202 | [Simple Object Access Protocol (SOAP)](https://en.wikipedia.org/wiki/SOAP) is a protocol for exchanging structured information over a network, most typically [Extensible Markup Language (XML)](https://en.wikipedia.org/wiki/XML) over HTTP. The standards are more stringent and have more implementation overhead than RESTful systems. This could be beneficial if you have compliance requirements. SOAP implementations should follow [ SOAP 1.2 specifications](http://www.w3.org/TR/soap12-part1/) and be [ WS-I Basic Profile 2.0](http://ws-i.org/profiles/BasicProfile-2.0-2010-11-09.html) compliant. 203 | 204 | More guidance for using SOAP in the OPS is available in [GO-ITS 24.0: Omnibus Web Services Standard](https://www.ontario.ca/document/go-its-240-omnibus-web-services-standard). 205 | 206 | ##### GraphQL 207 | [GraphQL](https://en.wikipedia.org/wiki/GraphQL) is a query language for building APIs designed to operate over a single endpoint. GraphQL requires the consumer to define the structure of the data that they want from the provider, which provides more granular control over data formats and more detailed analytics. GraphQL implementations should follow [industry best practices](https://graphql.org/learn/best-practices/). 208 | 209 | ##### RPC 210 | [Remote Procedure Call (RPC)](https://en.wikipedia.org/wiki/Remote_procedure_call) is a style of API design that focuses on operations (i.e. procedures) rather than resources. The consumer accesses endpoints that directly invoke a given function on the provider's server. This style of API design is best used if more complex interactions beyond CRUD (create, read, update, delete) are required. It is frequently used in conjunction with RESTful API design, though this is not strictly necessary. 211 | 212 | ##### gRPC 213 | [gRPC](https://grpc.io/) is an open source RPC system initially developed by Google. It uses a different serialization protocol than most HTTP APIs which improves the communication speed of requests. It generally is used internally between microservices, as it requires a defined contract (a .proto file) between services. 214 | 215 | ### Design meaningful data structures 216 | The design of the data structures that power the backend of the API can be just as important as the design of the software architecture of the API itself. Be thoughtful about how to structure the data that the API returns to the client. Consistent metadata and encoding ensure that APIs are interoperable both within and across organizations, and clearly structured response data is easier for the client to manipulate. 217 | 218 | #### Use descriptive data schemas 219 | Do not use generic data structures such as key-value pairs or generic fields. The constraints of a given data object should be apparent when reading the schema definition for that object type. Refer to [Schema.org](https://schema.org/) to see examples of well-designed data schemas. 220 | 221 | #### Use industry-standard information models for your discipline 222 | Avoid defining your own information model wherever possible. Instead, consider your business needs and see what information models other practitioners in your industry are using; for example, you might use [HL7](https://www.hl7.org/) for health data, or [GTFS](https://developers.google.com/transit/gtfs/) for transit data. If you *must* define your own information model, create a model that doesn't rely on a particular technology or platform and avoid getting locked into any particular vendor. 223 | 224 | If you're a developer within the Ontario Public Service, you can also refer to the following internal resources on information architecture: 225 | 226 | * [Standards for Developing Architecture](https://intra.ontario.ca/iit/standards-for-developing-architecture) 227 | * [Common Elements Data Model - Party LDM](https://intra.ontario.ca/wordpress/uploads/2017/05/CDEM-Party-LDM-v2.5.pdf) 228 | * [Common Data Elements - Address LDM](https://intra.ontario.ca/wordpress/uploads/2017/08/CDEM-Address-LDM-v2.3.pdf) 229 | * [GO-ITS 56.3 Information Modelling Standards Handbook](http://www.ontario.ca/government/go-its-563-information-modeling-handbook-imh-appendices) 230 | 231 | #### Abstract your raw data structures 232 | Do not expose raw data from your backend systems to end users. All data should go through a transformation phase so that unnecessary details are abstracted away and the resulting data object is designed for that business case. Exposing raw data structures can expose information about your internal operations and create security vulnerabilities. If you must expose raw data, *only* do so for open data, reporting and statistical APIs. 233 | 234 | For example, a transactional API that tracks purchase orders might sit on top of a database with confidential information about vendors. This information should be stripped out along with any other unnecessary data, so that the user only sees the order number and status. 235 | 236 | #### Omit debugging data 237 | All response data should be meaningful to the client, and should not expose any technical details that the developer might need for debugging. Do not include internal technical errors, thread dumps, process identifiers, or error messages within response data, even if the API call is unsuccessful. Exposing this information in a production environment can have major security implications. Instead, invest in a robust [logging system](#log-activity-and-performance). 238 | 239 | #### Be clear about your data encoding 240 | Use Unicode Transformation Format-8 ([UTF-8](http://unicode.org/faq/utf_bom.html#utf8-1)) as the standard encoding type for all text and textual representations of data through APIs. If technical or business constraints require the use of an encoding standard other than UTF-8, clearly identify the standard in the charset response header and API documentation. 241 | 242 | #### Use consistent date-time format 243 | For interoperability, all date-times should be sent in Coordinated Universal Time ([UTC](https://www.timeanddate.com/time/aboututc.html)). Dates and date-times should be expressed using [RFC 3339](https://tools.ietf.org/html/rfc3339) (e.g. YYYY-MM-DD or YYYY-MM_DDTHH:MM:SSZ). You may consider [ISO 8601](https://www.iso.org/standard/40874.html) if you cannot meet the requirements of RFC 3339. If UTC does not meet your requirements, a timezone offset must be included in the date-time. These formats allow for the same date-time representation in both official languages in 24-hour time. Any other representation of date-time in the source data should be converted to this format by the API. 244 | 245 | ### Iterate thoughtfully 246 | Take care to minimize the impact of your agile and iterative development on users so that they don't experience unnecessary or unexpected disruptions. 247 | 248 | #### Use semantic versioning 249 | Every released update to an API, no matter how small, must be tagged with a new version number in your version control system. Follow the [semantic versioning standard](https://semver.org/) to clearly signal the scope of each release and whether it is likely to break backwards compatibility. Each release should be tagged with `v..` (for example, `v2.3.1`). Major releases are the *only* releases that should introduce significant changes that may break backwards compatibility. Minor releases should indicate new backwards-compatible functionality or optional attributes, whereas patches should only be bug fixes or optimizations that do not impact how the API functions. 250 | 251 | #### Indicate major version in URL 252 | The major version of your API should be indicated in the URL of RESTful APIs, for example, api.ontario.ca/v3/endpoint. This makes it easier to support legacy versions of an API concurrently with the most recent version when releasing a major change that will break backwards compatibility. Do not pass versions as parameters or request headers. 253 | 254 | #### Deprecate gracefully 255 | Support at least one previous major version during a transition period to ensure that your users have enough notice to migrate their work, and communicate your development roadmaps with your users. For example, in a RESTful system, you can use the HTTP [Warning header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning) to announce upcoming changes. 256 | 257 | #### Test continuously 258 | You should adopt Continuous Integration and Delivery (CI/CD) supported by automation tools and integrated security testing. This creates a safety net that enables fast iteration, and is the first step on a pathway towards [DevOps automation](https://aws.amazon.com/devops/what-is-devops/). DevOps is an organizational philosophy and culture that tightly integrates deployment, operations, and security with day-to-day development for maximum efficiency and quality. 259 | 260 | Make sure your testing suite includes unit tests, integration tests and end-to-end tests. These should measure performance under a condition of average load while also identifying performance thresholds beyond which the API becomes unstable. Don't just test under ideal conditions. 261 | 262 | For example, if you're testing multiple components that talk to each other, make sure your end-to-end test is taking place in a live environment to get the most accurate latency information. Watch "[Avoiding Microservice Megadisasters - Jimmy Bogard](https://www.youtube.com/watch?v=gfh-VCTwMw8)" to see why this is a worthwhile practice. 263 | 264 | ### Practice security by design 265 | Even if your API does not expose protected or privileged data, it is still important to consider how to embed secure architecture design into your system. Not only is this good practice, it will also future-proof your API for future development. The following guidelines should be considered a *baseline* of security controls. Additional controls (for example, message-level encryption, mutual authentication and digital signatures) may also be required based on the sensitivity level of the data. 266 | 267 | Refer to the [ten principles of security by design](https://www.owasp.org/index.php/Security_by_Design_Principles) laid out by the Open Web Application Security Project for further guidance. 268 | 269 | #### Enforce secure communication 270 | Never send or store sensitive data in plaintext. Avoid using insecure or unencrypted connection wherever possible, even with non-sensitive data. 271 | 272 | * Sensitive data must be sent over TLS version 1.2 or later, and all certificates must be SHA-256 with a minimum key length of 2048. 273 | * Insecure traffic sent over HTTP should be rejected instead of automatically redirecting to HTTPS. Follow the cybersecurity standards from the [Government of Ontario Information Technology Standards (GO-ITS)](https://www.ontario.ca/page/information-technology-standards#section-6) where relevant, or consult the [Canadian Centre for Cyber Security](https://cyber.gc.ca/en/directives). 274 | 275 | #### Do not put sensitive data in request URLs 276 | Never accept sensitive data in URL or query strings, including API keys. The client must send this information via HTTP header or a JSON message payload so it can be properly encrypted. Even with transport encryption, URL strings can be tracked and compromised. 277 | 278 | #### Have a clearly-defined access policy 279 | Always authenticate, authorize, and validate any incoming request. With the exception of public open data APIs, all APIs should implement key-based authorization controls. APIs must only permit access for valid API keys and restrict access otherwise. You may need to consider other approaches to manage abuse, including rate limiting by IP address. 280 | 281 | Disable any unused HTTP verbs, and reject invalid requests to these endpoints. If relevant, use industry standards such as [ OpenID Connect](http://openid.net/connect/) and Open Authorization 2.0 ([OAuth 2.0](https://oauth.net/2/)) as an authentication protocol for RESTful APIs. Use Security Assertion Markup Language 2.0 ([SAML 2.0](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)) for SOAP APIs. 282 | 283 | #### Implement token management 284 | We strongly recommend token-based authentication. Ideally, use an open industry-standard token. 285 | 286 | * [JSON Web Token (JWT)](https://jwt.io/) for RESTful APIs 287 | * [WS-Security SAML Token Profile](http://docs.oasis-open.org/wss-m/wss/v1.1.1/wss-SAMLTokenProfile-v1.1.1.html) for SOAP APIs 288 | 289 | Avoid vendor proprietary token schemes, and do not attempt to create a custom token scheme from scratch. All tokens must expire within a reasonable amount of time, depending on security requirements. For example, token used for rate limiting may have a longer expiry time than tokens used for authentication. In the case of SAML, the assertion expiry must control the validity of the entire authentication and authorization session. 290 | 291 | #### Build internal security expertise around potential threat vectors 292 | There are many different ways of attacking and compromising an API. These are known as threat vectors. As it is impossible to cover all of them in this guide, it is important for each development team to develop an internal intuition and expertise around potential threats, and to design your API to be resilient for your specific needs. 293 | 294 | Some of the most common API attacks include: 295 | 296 | * [Injection attacks](https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html#introduction) involve attackers sending malformed input to the API with the intention of exposing security flaws. Some of the most prominent forms of this attack include SQL injection and XPath requests against XML. These can be partially mitigated with input validation. 297 | * [Replay attacks](https://auth0.com/docs/security/common-threats#replay-attacks) involve attackers copying a valid user request and masquerading as that user. Depending on the level of access the user had, this could result in attackers viewing and destroying private data. These can be partially mitigated with short token expiry times, blacklisting used tokens, and one-time passwords. 298 | 299 | ### Validate user input 300 | Any user input should be validated as soon as it is received, so that only properly formed and sanitized data is processed by your API. This will make your API more secure and also mitigate errors from malformed requests. 301 | 302 | #### Define clear request parameters 303 | Define what an appropriate request to your API looks like, including request size limit, content type, and range and format of any specific fields. If you are accepting string inputs, consider constraining these (for example, using regular expressions). 304 | 305 | #### Restrict open queries 306 | Dynamic and open queries not only constitute a dangerous threat vector, but they can also overly consume processing resources. Invest effort upfront to identify all the valid query uses cases and design the API to specifically meet them. If you must allow users to inject open query strings or objects into an API, these should be limited to open data, reporting, and statistical API only. Never permit open queries into an API with master data or with transactional APIs or business APIs. GraphQL can be used for statistical, analytics, and reporting purposes, but should not be used to support business transactions. 307 | 308 | #### Be cautious about wildcard characters 309 | Wildcards in APIs can be dangerous from a 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. Err on the side of rejecting a query with too many wildcards rather than risk timing out your database on the backend. 310 | 311 | #### Don't over-validate 312 | Before validating input, make sure the assumptions you're making about your user data are universally true. For example: 313 | 314 | * Names are not always "First M Last": [Falsehoods programmers believe about names](https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/) 315 | * Days aren't always exactly 24 hours: [Falsehoods programmers believe about time](https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time) 316 | * Email addresses can have surprising characters: [I Knew How To Validate An Email Address Until I Read The RFC](https://haacked.com/archive/2007/08/21/i-knew-how-to-validate-an-email-address-until-i.aspx/) 317 | 318 | ### Log activity and performance 319 | Good metrics form the basis of good evidence-based decision-making. Logs can provide information about attempted attacks, aid in post-mortem analyses, assess system performance, and suggest areas of product or feature improvement. 320 | 321 | #### Define performance measurements 322 | Different applications have different definitions of success. Rather than using the same benchmarks for every API, identify your key performance indicators prior to launch, and design measurement instruments that target those indicators specifically. Latency and response time will tell you different things about your API than user growth. 323 | 324 | #### Maintain meaningful logs 325 | All access to APIs should be tracked using industry logging standards (such as [common event format](https://help.deepsecurity.trendmicro.com/Events-Alerts/syslog-parsing.html)). If relevant, follow the logging requirements in [GO-ITS 25.0 General Security Requirements](https://www.ontario.ca/page/go-its-250-general-security-requirements) (3.4.2 and 3.4.3) and [GO-ITS 25.13 Security Requirements for Web Applications](https://www.ontario.ca/page/go-its-2513-security-requirements-web-applications) (section 2.9). These logs should be integrated centrally, and must include as a minimum both system and individual identifiers of the requesting client, as well as the timestamp. Ensure you don't inadvertently log confidential information (e.g. passwords). 326 | 327 | #### Review logs regularly 328 | API logs should be reviewed on a regular basis to monitor for suspicious usage or access patterns, such as after-hours requests, an unusually large volume of requests, or repeated input validation failures. Suspicious events must be sent to the Cyber Security Operations Centre, Cyber Security Division, Ministry of Government and Consumer Services. 329 | 330 | #### Audit sensitive access 331 | If your API provides personal or sensitive data, you must log when the data was accessed and by whom. This is needed in order to respond to data subject access requests, and will also help detect fraud or misuse. Consult your legal department for requirements on data retention and data custody policies. 332 | 333 | ### Optimize performance 334 | To ensure that your API can serve the needs of all users, carefully consider the size of each payload and the rate of responses. API performance should be benchmarked periodically to ensure you are continually meeting existing and projected business needs. 335 | 336 | #### Monitor and test performance 337 | It is important for your API to return results quickly and consistently. While speed is not the only metric that matters, [user experience research](https://www.nngroup.com/articles/powers-of-10-time-scales-in-ux/) suggests that a response time of 0.1 second (100ms) make users to feel like they're directly interacting with the system, while response times greater than 1 second are perceived as a noticeable slowdown. We recommend that you aim for a response time of at least 200ms, preferably 50ms. 338 | 339 | To achieve this, you should monitor ongoing performance and run regular performance tests to determine the response time and throughput. See section [Test continuously](#test-continuously). 340 | 341 | #### Rate limit user access where appropriate 342 | [Rate limiting](https://apisyouwonthate.com/blog/what-is-api-rate-limiting-all-about) is a good way of managing the amount of computing resources that an API requires. If widespread adoption of an API is expected or server costs are a concern, consider rate limiting each user based on how frequently they can call to the API, how much data they can request at once, or how many connections can live at once. 343 | 344 | Rate limiting also provides increases security by preventing a malicious actor from overloading the API with too many requests through a denial-of-service attack while making sure the system is kept available to all users. If the limit is exceeded, a standard HTTP 429 error can be returned. 345 | 346 | #### Implement pagination and data segmentation 347 | APIs exposing large datasets must support some form of data segmentation, both for the sake of optimizing the performance of the API and for a better user experience. The following are some common patterns for pagination along with appropriate use cases: 348 | 349 | * `page` and `per_page` are most appropriate when the dataset does not update frequently and the same set of data is likely to be returned given the same page reference over time, e.g. historical or reference data. 350 | * `offset` and `limit` are most appropriate for frequently updated data where users are likely to want to see data points older than (*offset* by) a given reference point, e.g. skipping past new articles you've already read. 351 | * `since` and `limit` are most appropriate for frequently updated data where users are likely to want to see new data points added *since*a given reference point, e.g. seeing all new content since your last visit. 352 | 353 | #### Apply special cases for bulk data sets 354 | 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, consider the following: 355 | 356 | * Smaller datasets should be returned in low overhead formats (e.g., CSV or JSON) rather than XML. Compressed file attachments should be avoided, especially when consuming external APIs, as they may conceal malicious content. 357 | * Trigger APIs initiate ("trigger") resource-heavy actions that are then carried out by a different system. They can start or stop events such as managed file transfers, which is more efficient than using the API to transfer the entire dataset. 358 | * Search-and-link APIs are best used to index existing file servers. These APIs return links to specific files, rather than the contents of those files. 359 | 360 | #### Define a caching policy 361 | If your API serves up data that is frequently requested but infrequently changed, consider implementing a response cache that stores the response to a GET request on a unique resource for quick retrieval. 362 | 363 | Caching best practices: 364 | 365 | * Consider using [key-based cache expiration](https://signalvnoise.com/posts/3113-how-key-based-cache-expiration-works) to avoid serving stale objects 366 | * Ensure that the cache is monitored to keep stale objects at a minimum 367 | * Ensure that the server has sufficient memory to handle caching loads 368 | * Be careful when caching non-public data to avoid inadvertently serving it to unauthorized users 369 | 370 | ### Documentation 371 | Each API must be accompanied by concise and up-to-date documentation on how to consume that API. The following practices help ensure APIs are documented appropriately without incurring the excess burden of managing companion documentation. 372 | 373 | #### Document both API specs and use cases 374 | Your documentation should include: 375 | 376 | * the technical specifications or contract of the API 377 | * how developers can use your API, including configuration, [authentication](#have-a-clearly-defined-access-policy) and [rate-limiting](#rate-limit-user-access-where-appropriate) 378 | * information about API availability, [versioning](#use-semantic-versioning), and incident management 379 | * [point of contact](#broadcast-your-intentions-dss-5) and a way for users to stay up-to-date with planned changes 380 | 381 | One effective way to help users get started quickly with your API is to publish code that makes use of it, such as test cases and validation data. See section on [testing continuously](#test-continuously). Example source code can be released on the [OPS Github Account](https://github.com/ongov). 382 | 383 | #### Use OpenAPI for RESTful APIs 384 | Use the [OpenAPI 3.0.n Specification](https://github.com/OAI/OpenAPI-Specification) for RESTful APIs. There are open source tools (e.g., [Swagger](https://swagger.io/solutions/api-documentation/)) which can be used to generate this code and create interactive, human-readable documentation for this specification. This specification avoids the need to create and maintain separate documentation. 385 | #### WSDLs for SOAP 386 | Each SOAP API must be accompanied with a Web Services Description Language ([WSDL](http://www.w3.org/TR/2007/REC-wsdl20-primer-20070626/)) contract. The WSDL is a machine-readable specification which allows the API consumer developer to generate the consumer code. 387 | 388 | #### Don't over-document 389 | Following the "[eat your own dog food](#consume-what-you-build)" principle, you should document the API to the degree that the documentation helps you and others build on the API, but not to the degree that the documentation is likely to become obtuse and obsolete. 390 | 391 | ## Future considerations 392 | One of the underlying principles of agile development is not to let the perfect become the enemy of the good. It is important to empower teams to deliver a solid minimum-viable service that is secure, robust, and scalable, without getting overly ambitious about nice-to-have features that delay launch and prevent real users from testing your service. Here are some additional things you should consider as you iterate your API and develop new features. 393 | 394 | ### Use an API Catalogue 395 | All APIs should be published to some sort of catalogue or inventory. Such an inventory can be a central repository of metadata and documentation, a lifecycle management point of contact for developers, and a portal for discovery for new users. This catalogue can also be integrated with a full-featured API gateway that directly manages the flow of traffic of the API, providing additional user management capabilities and security controls. Refer to the [API Store of the Federal Government of Canada](https://api.canada.ca/en/homepage/) or the [NASA API Portal](https://api.nasa.gov/) for examples of how this might look. 396 | 397 | Contact the Ontario Digital Service for more information on the status of an API catalogue for the Ontario Public Service. 398 | 399 | ### Define a Service Level Agreement 400 | Ideally, each API should be accompanied by a clearly defined Service Level Agreement (SLA), defining the following features: 401 | 402 | * Support hours (e.g., 24/7, 9/5, coast to coast business hours) 403 | * Service availability (e.g., 99%) 404 | * Support response time (e.g., within the hour, 24 hours, best effort) 405 | * Scheduled outages (e.g., nightly, weekly, every 2nd Sunday evening) 406 | * Throughput limit (e.g., 100 requests per second per consumer) 407 | * Message size limit (e.g., <1Mb per request) 408 | 409 | ### Publish source code and tests 410 | Publishing the source code for your API as open source has many benefits: 411 | 412 | * Allows a wider community of developers to spot potential problems with the code 413 | * Improves government transparency and accountability 414 | * Empowers other government departments to solve similar problems without reinventing the wheel 415 | * Contributes back to the open source community whose labour the government is benefiting from 416 | * Signals the technical expertise of the public service, which helps attract talent 417 | 418 | Even if you never intend on open sourcing your code, it is good practice to develop as though it will be scrutinized by the public. This can often provide an easy high-level overview of whether there are any gaping security holes. 419 | -------------------------------------------------------------------------------- /CONTRIBUTING-FR.md: -------------------------------------------------------------------------------- 1 | # Lignes directrices en matière de contributions 2 | 3 | ## Bienvenue! 4 | Nous sommes très heureux que vous songiez à contribuer à un projet des Services numériques de l’Ontario (SNO)! Si vous ne comprenez pas quelque chose, posez des questions – ou soumettez le problème ou la demande d’extraction de toute façon. Le pire qui pourrait arriver est qu’on vous demandera poliment de changer quelque chose. Nous aimons toutes les contributions amicales. 5 | 6 | Nous voulons nous assurer que tous nos projets profitent d’un environnement amical. Notre personnel respecte le code de conduite des SNO, et tous les contributeurs devraient en faire de même. 7 | 8 | Nous vous encourageons à lire la politique en matière de contributions de ce projet (vous y êtes), sa [licence](LICENCE-FR.md) et son fichier [README](README-FR.md). 9 | 10 | Vous pouvez partager vos réflexions et vos idées en : 11 | 12 | * nous envoyant un courriel à digital.standard@ontario.ca 13 | * créant une fourche à partir de notre référentiel GitHub 14 | 15 | ### Par courriel 16 | 17 | * Envoyez-nous les documents en texte en clair, comme les fichiers texte, les documents Word et les Google Docs par courriel 18 | * N’envoyez pas de documents en format HTML ou PDF, des documents imprimés ou des notes manuscrites 19 | * Dites-nous à quelle section vos suggestions s’appliquent 20 | * Si vous envoyez un courriel ou du texte en clair, incluez le texte original à des fins de consultation avec vos changements proposés 21 | * Si vous envoyez un document Word ou Google, utilisez le suivi des modifications ou le mode suggestion 22 | * Dites-nous la raison de votre suggestion et ses avantages 23 | 24 | ### Sur GitHub 25 | 26 | REMARQUE : La branche `develop` est une ébauche. La version officielle est dans la branche « master ». 27 | 28 | * Utilisez [Markdown](https://www.markdownguide.org/getting-started) pour formater vos changements 29 | * N’utilisez pas HTML, sauf si les changements que vous souhaitez apporter ne sont pas acceptés par Markdown (par exemple, des entêtes dans un tableau) 30 | * Créez une fourche à partir de notre branche `develop`, et faites une demande d’extraction vers « develop » lorsque vous êtes prêt à fusionner. 31 | * Nommez votre branche en utilisant votre prénom ou nom d’utilisateur, le type de changement (« fix » pour de petites modifications cosmétiques, « feature » pour les ajouts ou les suppressions), suivis d’une description de vos changements. Par exemple : `nom/fix/correcting-typos` OU `nom/feature/updates-to-standard` 32 | * Faites une validation par changement et expliquez la raison de votre changement dans votre message de validation (pas ce que vous avez changé, mais pourquoi) 33 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contribution guidelines 2 | 3 | ## Welcome! 4 | We're so glad you're thinking about contributing to an Ontario Digital Service (ODS) project! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions. 5 | 6 | We want to ensure a welcoming environment for all of our projects. Our staff follow the ODS Code of Conduct and all contributors should do the same. 7 | 8 | We encourage you to read this project's contributing policy (you are here), its [license](LICENSE.md), and its [README](README.md). 9 | 10 | You can share your thoughts and ideas by: 11 | 12 | * emailing us at digital.standard@ontario.ca 13 | * forking our GitHub repository 14 | 15 | ### By email 16 | 17 | * Send us plain text formats like text files, Word documents and Google docs by email 18 | * Do not send HTML, PDF, printed paper or handwritten notes 19 | * Tell us what section your suggestions apply to 20 | * If you’re sending email or plain text: include the original text for reference and your proposed changes 21 | * If you’re sending a Word or Google document: use track changes or suggest mode 22 | * Tell us the reason for your suggestion and the benefit it will have 23 | 24 | ### On GitHub 25 | 26 | NOTE: The `develop` branch is a working draft. The official version is in the master branch. 27 | 28 | * Use [Markdown](https://www.markdownguide.org/getting-started) to format your changes 29 | * Don't use HTML unless the changes you want to make are not supported in markdown (for example, headings inside a table) 30 | * Fork off of our `develop` branch, and make a pull request back to develop when you’re ready to merge. 31 | * Name your branch with your first name or user name, the type of change (“fix” for small cosmetic edits, “feature” for any additions or deletions), followed by a description of your changes. For example: `name/fix/correcting-typos` OR `name/feature/updates-to-standard` 32 | * Make one commit per change and explain the reasoning for your change in your commit message (not what you changed, but why) 33 | -------------------------------------------------------------------------------- /LICENCE-FR.md: -------------------------------------------------------------------------------- 1 | # Licence d’utilisation 2 | 3 | Le droit d’auteur de ce projet appartient à l’Imprimeur de la Reine en Ontario. 4 | 5 | Ce projet est visé par la [Licence publique Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/legalcode.fr) 6 | 7 | Toutes les contributions à ce projet seront publiées sous la même licence que ce fichier. En soumettant une demande d’extraction, vous acceptez de respecter la présente condition de la licence. 8 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | This project is copyright the Queen’s Printer in Ontario. 4 | 5 | This work is further licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). 6 | 7 | All contributions to this project will be released under the same licence as this file. By submitting a pull request, you are agreeing to comply with this licensing condition. 8 | -------------------------------------------------------------------------------- /Lignes-directrices-sur-les-API.md: -------------------------------------------------------------------------------- 1 | # Création de services numériques connectés : Lignes directrices sur les API 2 | 3 | ## Préface 4 | 5 | ### À propos de ce guide 6 | Ce guide s'adresse à toute personne qui développe des services numériques pour un service public, qu'il fasse partie de la Fonction publique de l'Ontario, d'un organisme gouvernemental ou d'autre chose. 7 | 8 | Les présentes lignes directrices se veulent être une feuille de route, et non un barrage. Elles visent à simplifier le développement de services numériques afin que les développeurs et les utilisateurs finaux puissent profiter d'un produit plus uniforme et plus robuste. 9 | 10 | ## Ce que les API peuvent faire 11 | Les interfaces de protocole d'application (API) laissent les applications se parler de façons structurées. Les développeurs de logiciels créent des API afin de partager des fonctionnalités ou des données provenant d'une application qu'ils ont développée avec toute personne qui souhaite travailler avec elle. 12 | 13 | Par exemple, lorsque vous regardez l'appli de météo sur votre téléphone, les renseignements que vous voyez proviennent d'une API fournie par votre service météorologique local. Son API prend les données sur les prédictions météorologiques et les convertit dans un format que d'autres développeurs d'applis peuvent utiliser. Cela permet aux développeurs de se concentrer sur la création d'une interface conviviale (par exemple, l'appli de météo de votre téléphone), sans devoir s'inquiéter de la science sous-jacente aux données. 14 | 15 | Les API ne se limitent pas à partager des données : elles peuvent être le tissu conjonctif entre de multiples systèmes associés, mais indépendants. Un organisme, comme le ministère des Transports de l'Ontario, qui délivre les permis de conduire pourrait créer une API qui prend un numéro de permis et vérifie s'il est expiré. Cette API serait très utile pour une entreprise de location de voitures qui souhaitent vérifier si le client possède un permis de conduire valide. 16 | 17 | ## Pourquoi les API sont importantes pour vous 18 | Les API vous permettent de créer des composants réutilisables et de développer une plateforme, ce qui vous évite d'avoir à réinventer la roue à chaque fois. Essentiellement, elles sont les éléments constitutifs d'un écosystème numérique. Comprendre la valeur des API vous aidera à adopter une approche qui commence par le numérique. 19 | 20 | Le partage des données et des processus par l'entremise d'API : 21 | 22 | * réduit le travail en double 23 | * encourage la communication et l'apprentissage entre les équipes 24 | * rend plus efficace le développement futur d'applications 25 | 26 | En suivant ce guide, vous vous assurerez que vos services sont : 27 | 28 | * interopérables avec d'autres plateformes et services 29 | * moins susceptibles d'être limités à un fournisseur ou une technologie en particulier 30 | * sont davantage pérennisés et plus faciles à mettre à jour et à tester 31 | 32 | Pour les équipes dans la Fonction publique de l'Ontario, les API permettent également aux organismes de satisfaire plus facilement à la [Directive sur les données ouvertes](https://www.ontario.ca/fr/page/directive-sur-les-donnees-ouvertes-de-lontario), qui exige que toutes les données du gouvernement soient publiques, sauf si elles sont spécifiquement exemptées. 33 | 34 | ### À qui s'adresse ce guide 35 | Vous devriez lire les présentes lignes directrices si vous êtes : 36 | 37 | * **un développeur ou une développeuse de logiciels** ou **un(e) architecte de systèmes** qui recherche des conseils techniques 38 | * **un(e) chef de produit** sur un produit d'API qui doit comprendre le contexte 39 | * **un(e) analyste de gestion** qui se demande si une API est une bonne solution pour votre problème 40 | * **un conseiller ou une conseillère en politiques** pour un service numérique qui cherche à mieux comprendre la manière dont les API peuvent contribuer à réaliser les objectifs en matière de politiques 41 | * **un concepteur ou une conceptrice de contenu**, **un concepteur ou une conceptrice d'expériences**, ou **un(e) praticien(ne) de toute autre discipline pertinente** qui souhaite se familiariser avec les principes décrits dans les présentes, afin de pouvoir y ajouter sa perspective 42 | 43 | ### Portés par des épaules de géants 44 | Nous avons adapté les présentes lignes directrices pour la Fonction publique de l'Ontario en nous basant sur l'excellent travail d'autres gouvernements numériques, y compris : 45 | 46 | * [Le gouvernement du Canada](https://www.canada.ca/fr/gouvernement/systeme/gouvernement-numerique/technologiques-modernes-nouveaux/normes-gouvernement-canada-api.html) 47 | * [Le Service numérique du Royaume-Uni](https://www.gov.uk/guidance/gds-api-technical-and-data-standards) (en anglais) 48 | * [18F (la General Services Administration des États-Unis)](https://github.com/18F/api-standards) (en anglais) 49 | * [Le gouvernement de Nouvelle-Zélande](https://snapshot.ict.govt.nz/guidance-and-resources/standards-compliance/api-standard-and-guidelines/index.html) (en anglais) 50 | * [Le gouvernement de l'État de Victoria, Australie](https://github.com/VictorianGovernment/api-design-standards) (en anglais) 51 | 52 | ## Facteurs relatifs aux activités et aux processus 53 | Si vous développez une API pour la Fonction publique de l'Ontario, vous devez respecter la [Norme des services numériques](https://www.ontario.ca/fr/page/norme-des-services-numeriques) (NSN) du gouvernement de l'Ontario. Même si vous ne faites pas partie de la FPO, nous vous encourageons tout de même à vous familiariser avec la NSN, qui présente 14 principes clés pour le développement de bons services axés sur les utilisateurs. 54 | 55 | ### Consommez ce que vous créez 56 | La meilleure façon de vous assurer que votre API est bien conçue consiste à l'utiliser vous-même dans une application en production. Dans le secteur technique, ce processus est appelé « dogfooding ». 57 | 58 | Essayez toujours de créer vos API en parallèle avec un cas d'utilisation interne qui sera intégré avec l'API avant que celui-ci soit publié pour un usage externe. Le cas d'utilisation interne peut servir de projet pilote peu visible que vous utilisez pour valider vos hypothèses concernant la manière de concevoir l'API et vous permettra de pivoter et d'adapter votre conception, au besoin. Il vous force également à réfléchir du point de vue de l'utilisateur et de ses besoins. 59 | 60 | Assurez-vous que la conception de votre API tient compte des différentes façons dont elle pourrait être utilisée par votre public, y compris : 61 | 62 | * les systèmes internes de la FPO 63 | * des partenaires de confiance 64 | * le public 65 | 66 | Si vous devez limiter l'accès d'un public à certains composants, intégrez des capacités de gestion des utilisateurs, au lieu de créer de multiples API. Cette approche permettra également de faire ressortir tout problème de sécurité potentiel dès le début, alors qu'ils peuvent être réglés de façon proactive. 67 | 68 | ### Parlez à vos utilisateurs ([NSN no 1](https://www.ontario.ca/fr/page/norme-des-services-numeriques#section-1)) 69 | Travaillez avec les personnes qui utiliseront l'API pour s'assurer que votre architecture et votre conception répondent à leurs besoins. Utilisez les services d'experts en conception de l'expérience utilisateur pour effectuer des recherches auprès : 70 | 71 | * d'utilisateurs techniques 72 | * de domaines d'affaires et de programmes 73 | 74 | Les API devraient être créées pour satisfaire des exigences d'affaires précises afin de résoudre des problèmes concrets. Si vous ne savez pas quel besoin des utilisateurs est satisfait par l'API, ou si vous créez simplement l'API pour exposer des données sans savoir à quoi elles serviront, cela indique probablement que l'API n'est pas la bonne solution. 75 | 76 | ### Utilisez des normes ouvertes ([NSN no 9](https://www.ontario.ca/fr/page/norme-des-services-numeriques#section-9)) 77 | Si possible, créez votre API en utilisant des outils, des cadres et des normes ouverts. Les communautés ouvertes qui développent ces outils travaillent grâce à la collaboration et au développement de consensus, et les participants vont de contributeurs individuels qui travaillent dans leurs temps libres à d'importantes entreprises technologiques. La diversité des voix permet de s'assurer que les outils visent l'interopérabilité, la sécurité, la fiabilité et l'accessibilité. De plus, parce que ces outils ne sont pas associés à un fournisseur ou un système en particulier, vous n'exclurez pas les utilisateurs de l'extérieur de la FPO. 78 | 79 | ### Effectuez de fréquentes itérations ([NSN no 8](https://www.ontario.ca/fr/page/norme-des-services-numeriques#section-8)) 80 | La Norme des services numériques de l'Ontario inclut [une approche agile du développement](https://www.ontario.ca/fr/page/norme-des-services-numeriques#section-8). Cela signifie que vous pouvez bâtir votre application en « itérations » qui améliorent un ensemble de fonctions à la fois, ce qui vous permet : 81 | 82 | * de tester rapidement votre service auprès de vrais utilisateurs 83 | * de prouver ou de réfuter vos hypothèses 84 | * de réagir plus rapidement aux changements des exigences, des politiques ou de la technologie 85 | 86 | Plus il est facile d'effectuer des itérations avec votre API, plus elle sera facile à utiliser par les autres utilisateurs. 87 | 88 | ### Intégrez la protection de la vie privée au niveau de la conception ([NSN no 10](https://www.ontario.ca/fr/page/norme-des-services-numeriques#section-10)) 89 | Bien qu'il soit important de minimiser les obstacles à l'accès aux programmes gouvernementaux, il est également important de protéger les données sensibles et de minimiser le potentiel d'atteintes à la protection des données. 90 | 91 | Évaluez les données qui seront partagées par l'entremise de l'API. Lorsque vous travaillez avec : 92 | 93 | * des données qui ne sont pas sensibles, créez des API qui peuvent être utilisées par le public, avec un minimum d'obstacles 94 | * des données sensibles, mettez en place des mesures appropriées en matière juridique, de sécurité et de protection de la vie privée pour éviter tout mésusage des données 95 | 96 | Pour obtenir de plus amples renseignements, consultez les [sept principes de la protection de la vie privée au niveau de la conception](https://www.ryerson.ca/pbdce/certification/seven-foundational-principles-of-privacy-by-design/) (en anglais). 97 | 98 | ### Faites connaître vos intentions ([NSN no 5](https://www.ontario.ca/fr/page/norme-des-services-numeriques#section-5)) 99 | Tenez vos utilisateurs au courant de vos plans pour l'API. Travaillez avec eux pour les aider à comprendre les répercussions de tout changement majeur prévu. 100 | 101 | Lorsque vous publiez des mises à jour à une API qui contiennent des changements qui ne sont pas [rétrocompatibles](#utilisez-la-gestion-semantique-de-version) et qui exigent que vos partenaires développeurs mettent leur code à jour, assurez-vous de définir et de communiquer des échéanciers clairs de dépréciation. Cela permet aux développeurs de passer à la nouvelle version avant que l'ancienne version qu'ils utilisent soit mise hors service, et évite de perturber leur travail. 102 | 103 | Assurez-vous que chaque API a au moins un point de contact désigné pour les équipes qui l'utilisent : 104 | 105 | * toutes les API ont besoin d'un compte de courriel publié pour le soutien 106 | * un numéro de téléphone est également requis pour les API très critiques 107 | * l'idéal est de publier une page de statut sur laquelle les utilisateurs peuvent trouver les indisponibilités prévues et imprévues, et les derniers renseignements concernant la disponibilité et le statut de l'API 108 | 109 | ### Assurez-vous que vous avez vraiment besoin d'une API 110 | Les API comptent parmi les nombreuses façons d'intégrer les données et les fonctions entre les systèmes, mais elles ne sont pas toujours la meilleure ou l'unique solution. Si vous devez archiver une grande quantité de relations complexes entre les données une fois par an, un [système de transfert de données en vrac](https://fr.wikipedia.org/wiki/Transmission_de_donn%C3%A9es) pourrait s'avérer préférable. Ou s'il est peu probable que l'application client et le serveur soient en ligne en même temps et ils doivent communiquer de façon asynchrone, une [file de messagerie](https://aws.amazon.com/fr/message-queue/) pourrait être une solution plus appropriée. Les API sont à leur plus utile si vous soutenez des interactions entre les systèmes et l'accès aux données en temps réel. 111 | 112 | ## Facteurs techniques 113 | ### Concevez des API passives 114 | Chaque appel à l'API doit contenir tous les renseignements requis pour répondre à la demande, sans s'attendre à ce que le serveur se souvienne de quoi que ce soit concernant des demandes ou des contextes précédents. Cela porte le nom de conception passive. 115 | 116 | Ne stockez pas de renseignements concernant les états des sessions sur le serveur de l'API. Toute forme de gestion des états—par exemple sous la forme de témoins ou d'ID de session—doit être conservée par le client qui envoie la demande. Il est donc plus facile pour votre API de détecter les erreurs et de les réparer, car chaque erreur est contenue à l'intérieur d'une seule demande et ne concerne pas la totalité de l'état du serveur. 117 | 118 | La conception d'une API passive améliore également l'évolutivité de votre serveur, car les ressources de traitement peuvent être libérées rapidement pour chaque demande, sans qu'il soit nécessaire de conserver les transactions incomplètes en mémoire cache. 119 | 120 | ### Si possible, respectez le style REST 121 | Dans la grande majorité des cas d'utilisation, nous recommandons la conception d'API [REST](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) (en anglais). Le transfert d'état représentationnel (REST) est la plus importante norme d'intégration avec les services dans le nuage, et est également la norme définie par la majorité des autres gouvernements qui ont des programmes d'API bien établis. Suivez les [meilleures pratiques](https://restfulapi.net/) (en anglais) du secteur lorsque vous effectuez la conception et le développement de votre API REST. Notamment : 122 | 123 | #### Représentez les ressources en tant qu'URL 124 | Chaque URL terminale dans la conception d'une API REST devrait représenter une entité, une ressource ou un objet de gestion. Par exemple, une API de ServiceOntario (SO) pourrait fournir des points terminaux permettant de voir des renseignements concernant un seul emplacement de SO. 125 | 126 | * **À FAIRE** : `api.ontario.ca/bureaux/emplacement/college-park` 127 | 128 | N'utilisez pas les points terminaux pour effectuer des opérations sur ces entités ou objets. Cela signifie que vos schémas d'URL devraient être composés de noms et pas de verbes. 129 | 130 | * **À NE PAS FAIRE** : `api.ontario.ca/obtenirHeuresdOuverture/college-park` 131 | 132 | #### Utilisez des URI pour identifier les ressources 133 | Si les données de la réponse contiennent des références à d'autres ressources dans l'API, incluez une URL complète vers le point terminal pour cette ressource. Cela permettra à l'utilisateur de suivre les références des données pour des activités futures avec un minimum d'efforts. 134 | 135 | Si des données sont renvoyées dans une réponse, utilisez des identificateurs de ressources uniformes (URI) pour identifier de façon unique chaque ressource de données. Cela permettra au client ou au système consommateur de faire référence directement à cette donnée pour des activités futures, avec un remaniement mineur. 136 | 137 | Par exemple, un point terminal qui fournit des renseignements sur les emplacements de ServiceOntario à proximité d'une adresse donnée devrait être lié directement aux points terminaux pour chacun de ces emplacements, au lieu de se contenter d'énumérer les noms. 138 | 139 | * **À FAIRE** : 140 | ``` 141 | { 142 | proche: [{ 143 | nom: "University Avenue", 144 | url: "api.ontario.ca/location/university-ave" 145 | }] 146 | } 147 | ``` 148 | 149 | * **À NE PAS FAIRE** : 150 | ``` 151 | { 152 | proche: ["University Avenue"] 153 | } 154 | ``` 155 | 156 | #### Renvoyez les données en format JSON 157 | Utilisez la notation des objets du langage JavaScript ([JSON](https://www.json.org/) (en anglais)) et d'autres représentations basées sur JSON (comme [JSON-LD](https://json-ld.org/) (en anglais)) pour transmettre des données entre un client et un serveur. Les réponses envoyées par l'API au client devraient être formées comme des objets et non des tableaux ou des valeurs. Les tableaux ne sont pas suffisamment robustes pour inclure des métadonnées adéquates concernant l'objet résultat, ce qui peut rendre plus difficile l'itération lors de la conception des données. 158 | 159 | Par exemple, un point terminal qui énumère tous les emplacements de ServiceOntario devrait inclure leur nombre. 160 | 161 | * **À FAIRE** : 162 | ``` 163 | { 164 | totale: 234 165 | emplacements: [ ... ] 166 | } 167 | ``` 168 | 169 | * **À NE PAS FAIRE** : 170 | ``` 171 | [ 172 | { id: university-ave ... }, 173 | { id: college-park ... } 174 | ] 175 | ``` 176 | Assurez-vous que la conception de vos objets de données est prévisible et facile à utiliser. Suivez une grammaire cohérente pour nommer les clés d'objets, et n'utilisez pas de données réelles pour créer des clés d'objets dynamiques. 177 | 178 | #### Ne surchargez pas les méthodes d'appel au protocole HTTP 179 | 180 | Chaque [méthode d'appel au protocole HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) (en anglais)—aussi appelée verbe HTTP—devrait représenter une seule opération sur une ressource donnée ou une liste de ressources. N'utilisez pas de paramètres de demande pour définir des opérations supplémentaires; par exemple, n'utilisez pas GET pour faire quelque chose d'autre que récupérer des données. Voici les utilisations idiomatiques des verbes HTTP dans le contexte d'une API REST : 181 | 182 | * `GET` – obtenir une ressource 183 | * `POST` – créer une nouvelle ressource 184 | * `PUT` – mettre à jour ou remplacer une ressource existante 185 | * `DELETE` – supprimer une ressource 186 | 187 | Ces opérations sont également parfois appelées « `CRUD` » (Create, Read, Update, Delete – Créer, lire, mettre à jour, supprimer). 188 | 189 | #### Utilisez des entêtes d'acceptation standard 190 | 191 | Toute négociation entre le client et le serveur concernant le type de données demandées doit être effectuée en utilisant des [entêtes HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (en anglais). Les entêtes de demande ACCEPT et CONTENT-TYPE sont obligatoires, et les entêtes AUTHORIZATION sont obligatoires pour les API sécurisées. Les clés de l'API doivent être transférées dans l'entête, et non dans l'URL de demande. 192 | 193 | Si votre API accepte plusieurs langues, l'entête ACCEPT-LANGUAGE doit être envoyé par le client, et le serveur doit renvoyer le contenu dans la langue demandée. Si l'entête de langue n'est pas défini dans un système multilingue, le contenu doit être renvoyé dans toutes les langues acceptées. Les différentes langues devraient être imbriquées sous les [codes de langue BCP-47](https://tools.ietf.org/html/bcp47) (en anglais) (p. ex., « en », « fr ») comme clés d'objets. Les données renvoyées dans la réponse doivent contenir au minimum l'entête CONTENT-TYPE. 194 | 195 | #### Utilisez des codes d'erreur normalisés 196 | 197 | Lorsque vous créez des API REST, utilisez des [codes d'état HTTP](https://restfulapi.net/http-status-codes/) (en anglais) standard. Respectez les [anomalies SOAP 1.2](http://www.w3.org/TR/soap12-part1/#soapfault) (en anglais) lorsque vous créez des API SOAP. Évitez de développer des codes d'erreur et des schémas de données sur mesure : le client doit faire davantage de travail pour les analyser. 198 | 199 | #### Solutions de rechange à REST 200 | 201 | Les API REST ne seront pas la meilleure solution pour chaque problème d'affaires, particulièrement s'il existe des contraintes techniques du côté du fournisseur ou du côté du consommateur. Voici quelques exemples d'autres architectures d'API que vous pourriez considérer : 202 | 203 | ##### SOAP 204 | [Le protocole SOAP (Simple Object Access Protocol)](https://en.wikipedia.org/wiki/SOAP) (en anglais) est un protocole permettant d'échanger des renseignements structurés sur un réseau, le plus souvent [par langage XML (langage de balisage extensible)](https://en.wikipedia.org/wiki/XML) (en anglais) sur HTTP. Les normes sont plus strictes et sa mise à jour exige plus de temps système que les systèmes REST. Cela pourrait être utile si vous avez des exigences en matière de conformité. Les mises à jour SOAP devraient respecter les [spécifications SOAP 1.2](http://www.w3.org/TR/soap12-part1/) (en anglais) et être conformes à [WS-I Basic Profile 2.0](http://ws-i.org/profiles/BasicProfile-2.0-2010-11-09.html) (en anglais). 205 | 206 | D'autres lignes directrices sur l'utilisation de SOAP dans la FPO sont disponibles dans le document [NTI-GO 24.0 Norme omnibus pour les services Web](https://www.ontario.ca/fr/document/nti-go-240-norme-omnibus-pour-les-services-web). 207 | 208 | ##### GraphQL 209 | [GraphQL](https://en.wikipedia.org/wiki/GraphQL) (en anglais) est un langage d'interrogation pour la création d'API conçues pour fonctionner avec un seul point terminal. GraphQL exige que le consommateur définisse la structure des données qu'il souhaite obtenir auprès du fournisseur, ce qui procure un contrôle plus granulaire sur les formats de données et une analytique plus détaillée. Les mises en œuvre de GraphQL devraient respecter les [meilleures pratiques du secteur](https://graphql.org/learn/best-practices/) (en anglais). 210 | 211 | ##### RPC 212 | [L'appel de procédure à distance (Remote Procedure Call ou RPC)](https://en.wikipedia.org/wiki/Remote_procedure_call) (en anglais) est un style de conception d'API qui met l'accent sur les opérations (c.-à-d. procédures) plutôt que sur les ressources. Le consommateur accède à des points terminaux qui invoquent directement une fonction donnée sur le serveur du fournisseur. Ce style de conception d'API est préférable si des interactions plus complexes que les opérations CRUD sont requises. Il est souvent utilisé conjointement avec la conception d'API REST, bien que cela ne soit pas strictement nécessaire. 213 | 214 | ##### gRPC 215 | [gRPC](https://grpc.io/) (en anglais) est un système de RPC ouvert initialement développé par Google. Il utilise un protocole de sérialisation différent de la plupart des API HTTP, ce qui améliore la vitesse de communication des demandes. Il est généralement utilisé de façon interne entre les microservices, car il exige un contrat défini (c.-à-d. un protofichier) entre les services. 216 | 217 | ### Effectuez la conception de structures de données ayant un sens 218 | La conception des structures de données qui alimentent le programme de fond de l'API peut être tout aussi importante que la conception de l'architecture logicielle de l'API elle-même. Réfléchissez bien à la façon de structurer les données qui sont renvoyées au client par l'API. Des métadonnées et un codage cohérent permettent de s'assurer que les API sont interopérables au sein des organisations et entre celles-ci, et des données de réponse clairement structurées sont plus faciles à manipuler par le client. 219 | 220 | #### Utilisez des schémas de données descriptifs 221 | N'utilisez pas de structures de données génériques, comme des pairs clé-valeur ou des champs génériques. Les contraintes d'un objet de donnée quelconque devraient être apparentes à la lecture de la définition du schéma pour ce type d'objet. Consultez [Schema.org](https://schema.org/) (en anglais) pour voir des exemples de schémas de données bien conçus. 222 | 223 | #### Utilisez les modèles d'information qui sont des normes dans le secteur pour votre discipline 224 | Si possible, évitez de définir votre propre modèle d'information Examinez plutôt vos besoins d'affaires et voyez quels modèles d'information sont utilisés par d'autres praticiens dans votre secteur—par exemple, vous pourriez utiliser [HL7](https://www.hl7.org/) (en anglais) pour les données sur la santé, ou [GTFS](https://developers.google.com/transit/gtfs/) (en anglais) pour des données de transport en commun. Si vous devez définir votre propre modèle d'information, créez-en un qui ne dépend pas d'une technologie ou d'une plateforme en particulier, et évitez de vous limiter à un fournisseur en particulier. 225 | 226 | Si vous êtes un développeur au sein de la Fonction publique de l'Ontario, vous pouvez également consulter les ressources internes suivantes sur l'architecture de l'information : 227 | 228 | * [Standards for Developing Architecture](https://intra.ontario.ca/iit/standards-for-developing-architecture) (en anglais) 229 | * [Common Elements Data Model - Party LDM](https://intra.ontario.ca/wordpress/uploads/2017/05/CDEM-Party-LDM-v2.5.pdf) (en anglais) 230 | * [Common Data Elements - Address LDM](https://intra.ontario.ca/wordpress/uploads/2017/08/CDEM-Address-LDM-v2.3.pdf) (en anglais) 231 | * [NTI-GO 56.3 Annexes du Manuel sur la modélisation de l'information](https://www.ontario.ca/fr/document/nti-go-563-annexes-du-manuel-sur-la-modelisation-de-linformation-mmi) (en anglais) 232 | 233 | #### Rendez abstraites les structures de vos données brutes 234 | N'exposez pas les données brutes de vos systèmes dorsaux aux utilisateurs finaux. Toutes les données devraient traverser une phase de transformation afin que les détails inutiles soient supprimés et que l'objet de donnée qui en résulte soit conçu pour ce dossier d'analyse. L'exposition des structures des données brutes peut exposer de l'information sur vos activités internes et créer des vulnérabilités en matière de sécurité. Si vous devez exposer des données brutes, faites-le seulement pour des API de données ouvertes, de rapports et de statistiques. 235 | 236 | Par exemple, une API transactionnelle qui effectue le suivi de bons de commande pourrait être par-dessus d'une base de données contenant des renseignements confidentiels sur les fournisseurs. Ces renseignements devraient être supprimés avec les autres données inutiles, afin que l'utilisateur ne voie que le numéro de commande et le statut. 237 | 238 | #### Omettez les données de débogage 239 | Toutes les données de la réponse devraient avoir un sens pour le client et ne pas exposer de détails techniques dont le développeur pourrait avoir besoin pour le débogage. N'incluez pas les erreurs techniques, le vidage des fils, les identifiants de processus ou les messages d'erreur dans les données de la réponse, même si l'appel à l'API n'a pas réussi. L'exposition de ces renseignements dans un environnement de production peut avoir des répercussions majeures sur la sécurité. Investissez plutôt dans un [système d'enregistrement](#consignez-lactivit%C3%A9-et-la-performance) robuste. 240 | 241 | #### Soyez clair concernant le codage de vos données 242 | Utilisez le format [UTF-8](http://unicode.org/faq/utf_bom.html#utf8-1) (Unicode Transformation Format-8) (en anglais) comme type de codage standard pour la totalité du texte et des représentations textuelles des données par l'entremise d'API. Si des contraintes techniques ou d'affaires exigent l'utilisation d'une norme de codage autre que UTF-8, identifiez clairement la norme dans l'entête de réponse charset et la documentation de l'API. 243 | 244 | #### Utilisez un format uniforme de date et d'heure 245 | Suivez la norme internationale [ISO 8601](https://www.iso.org/fr/standard/40874.html) en temps universel coordonné ([UTC](https://www.timeanddate.com/time/aboututc.html) (en anglais)) pour les champs standard de date et d'heure dans les données renvoyées par l'API. Le format de date est ``, et le format de l'heure système est `TZ` en format 24 heures. Cela permet de représenter la date de la même façon dans les deux langues. Toute autre représentation de l'heure dans les données source doit être convertie à ce format par l'API. 246 | 247 | ### Pensez avant d'itérer 248 | Assurez-vous de minimiser l'impact sur les utilisateurs de votre développement agile et itératif afin qu'ils ne soient pas victimes de perturbations inutiles ou inattendues. 249 | 250 | #### Utilisez la gestion sémantique de version 251 | Chaque mise à jour publiée d'une API, si petite soit-elle, doit porter un nouveau numéro de version dans votre système de contrôle des versions. Suivez la [norme de gestion sémantique de version](https://semver.org/lang/fr/) afin d'indiquer clairement la portée de chaque version et si elle est susceptible de contenir des changements non rétrocompatibles. Chaque version devrait porter un identifiant `v..` (par exemple, `v2.3.1`). Les versions majeures sont les seules qui devraient introduire des changements importants qui pourraient être non rétrocompatibles. Les versions mineures devraient désigner des ajouts de fonctionnalités rétrocompatibles ou des attributs facultatifs, tandis que les correctifs ne devraient être que des corrections de bogues ou des anomalies mineures qui n'affectent pas le changement de l'API. 252 | 253 | #### Indiquez la version majeure dans l'URL 254 | La version majeure de votre API devrait être indiquée dans l'URL des API REST, par exemple api.ontario.ca/v3/endpoint. Cela permet de soutenir plus facilement d'anciennes versions d'une API en même temps que la version la plus récente lors de la publication d'un changement majeur qui n'est pas rétrocompatible. Ne transférez pas les versions en tant que paramètres ou entêtes de demandes. 255 | 256 | #### Dépréciez de façon gracieuse 257 | Soutenez au moins une version majeure précédente pendant une période de transition pour vous assurer que vos utilisateurs ont un préavis suffisant pour transférer leur travail, et communiquez vos feuilles de route du développement avec vos utilisateurs. Par exemple, dans un système REST, vous pouvez utiliser [l'entête Warning](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning) (en anglais) de HTTP pour annoncer les changements prochains. 258 | 259 | #### Effectuez constamment des essais 260 | Vous devriez adopter la méthode d'intégration continue et de livraison continue (CI/CD), soutenue par des outils d'automatisation et des essais de sécurité intégrés. Cela crée un filet de sécurité qui permet l'itération rapide et devient la première étape sur un parcours vers [l'automatisation DevOps](https://aws.amazon.com/fr/devops/what-is-devops/) (en anglais). DevOps est une philosophie et une culture organisationnelle qui intègre étroitement le déploiement, les activités et la sécurité avec le développement quotidien pour une efficacité et une qualité maximales. 261 | 262 | Assurez-vous que votre suite de tests inclut des tests unitaires, des tests d'intégration et des tests de bout en bout. Ceux-ci devraient mesurer la performance sous une charge moyenne, tout en identifiant les seuils de performance au-delà desquels l'API devient instable. N'effectuez pas vos tests uniquement dans des conditions idéales. 263 | 264 | Par exemple, si vous testez de multiples composants qui communiquent ensemble, assurez-vous que vos tests de bout en bout ont lieu dans un environnement réel, afin d'obtenir les renseignements les plus exacts sur la latence. Regardez « [Avoiding Microservice Megadisasters – Jimmy Bogard](https://www.youtube.com/watch?v=gfh-VCTwMw8) (en anglais) » pour voir pourquoi il s'agit d'une pratique louable. 265 | 266 | ### Intégrez la sécurité au niveau de la conception 267 | Même si votre API n'expose pas de données protégées ou privilégiées, il est tout de même important d'étudier la manière d'incorporer la conception d'une architecture sécurisée dans votre système. Cela est une bonne pratique qui vous permettra également de préparer votre API pour les développements futurs. Les lignes directrices devraient être considérées comme des mesures de sécurité de base. Des mesures de contrôle supplémentaires (par exemple, chiffrement au niveau du message, authentification mutuelle et signatures numériques) pourraient également être requises, selon le niveau de sensibilité des données. 268 | 269 | Pour obtenir de plus amples renseignements, consultez les [dix principes de la sécurité au niveau de la conception](https://www.owasp.org/index.php/Security_by_Design_Principles) (en anglais) présentés par l'Open Web Application Security Project. 270 | 271 | #### Imposez une communication sécurisée 272 | Il ne faut jamais envoyer ou stocker des données sensibles en clair. Évitez d'utiliser une connexion non sécurisée ou non chiffrée dans la mesure du possible, même avec des données qui ne sont pas sensibles. 273 | 274 | * Les données sensibles doivent être envoyées via TLS version 1.2 ou plus, et tous les certificats doivent être SHA-256 avec une longueur de clé minimale de 2048. 275 | * Le trafic non sécurisé envoyé sur HTTP devrait être refusé au lieu d'être réacheminé automatiquement à HTTPS. Suivez les normes de cybersécurité des [normes de technologies de l'information (NTI-GO) du gouvernement de l'Ontario ](https://www.ontario.ca/fr/page/normes-en-technologie-de-linformation#section-6) lorsqu'elles sont pertinentes, ou consultez le [Centre canadien pour la cybersécurité](https://cyber.gc.ca/fr/directives) (en anglais). 276 | 277 | #### Ne mettez pas de données sensibles dans les URL de demande 278 | N'acceptez jamais de données sensibles dans les URL ou les chaînes d'interrogation, y compris les clés API. Le client doit envoyer cette information dans un entête HTTP ou les données utiles d'un message JSON afin qu'elle puisse être chiffrée correctement. Même avec le chiffrement pendant le transport, les chaînes URL peuvent être suivies et compromises. 279 | 280 | #### Établissez une politique d'accès clairement définie 281 | Authentifiez, autorisez et validez toujours les demandes entrantes. À l'exception des API ouvertes publiques suivantes, toutes les API devraient mettre en œuvre des contrôles sur l'autorisation basés sur des clés. Les API ne doivent permettre l'accès qu'aux clés d'API valides et restreindre l'accès autrement. Vous pourriez devoir envisager d'autres approches de gestion des abus, y compris la limitation du débit par adresse IP. 282 | 283 | Désactivez tout verbe HTTP inutilisé et rejetez les demandes invalides vers ces points terminaux. Si cela est pertinent, utilisez des normes du secteur comme [ OpenID Connect](http://openid.net/connect/) (en anglais) et Open Authorization 2.0 ([OAuth 2.0](https://oauth.net/2/) (en anglais)) comme protocole d'authentification pour les API REST. Utilisez le Security Assertion Markup Language 2.0 ([SAML 2.0](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) (en anglais)) pour les API SOAP. 284 | 285 | #### Mettez en œuvre la gestion des jetons 286 | Nous recommandons fortement une authentification basée sur des jetons. L'idéal est d'utiliser un jeton ouvert qui est standard dans l'industrie. 287 | 288 | * [JSON Web Token (JWT)](https://jwt.io/) (en anglais) pour les API REST 289 | * [WS-Security SAML Token Profile](http://docs.oasis-open.org/wss-m/wss/v1.1.1/wss-SAMLTokenProfile-v1.1.1.html) (en anglais) pour les API SOAP 290 | 291 | Évitez les schémas de jetons exclusifs à un fournisseur, et ne tentez pas de créer un schéma de jetons sur mesure à partir de zéro. Tous les jetons doivent expirer au bout d'un délai raisonnable, selon les exigences de la sécurité. Par exemple, le jeton utilisé pour la limitation de la vitesse peut avoir un délai d'expiration plus long que les jetons utilisés pour l'authentification. Dans le cas de SAML, l'expiration de l'assertion doit contrôler la validité de toute la session d'authentification et d'autorisation. 292 | 293 | ### Développez des compétences internes en matière de sécurité concernant des vecteurs potentiels de menaces 294 | Il existe de nombreuses façons d'attaquer et de compromettre une API. Elles portent le nom de vecteurs de menaces. Comme il est impossible de les couvrir tous dans ce guide, il est important que chaque équipe de développement acquière une intuition et des compétences internes relativement aux menaces possibles et effectue la conception de l'API afin de la rendre résiliente pour vos propres besoins. 295 | 296 | Voici certaines des attaques les plus courantes sur les API : 297 | 298 | * Lors des [attaques par injection](https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html#introduction) (en anglais), les attaquants envoient des données entrantes mal formées à l'API dans le but d'exposer les lacunes en matière de sécurité. Certaines des formes les plus connues de cette attaque comprennent l'injection SQL et les demandes XPath à XML. Elles peuvent être partiellement atténuées avec la validation des données entrantes. 299 | * Lors des [attaques par rejeu](https://auth0.com/docs/security/common-threats#replay-attacks) (en anglais), les attaquants copient la demande valide d'un utilisateur et se font passer pour celui-ci. Selon le niveau d'accès dont disposait l'utilisateur, les attaquants pourraient voir et détruire des données privées. Elles peuvent être partiellement atténuées avec de courts délais d'expiration des jetons, l'inscription des jetons utilisés sur une liste noire, et des mots de passe à usage unique. 300 | 301 | ### Validez les données saisies par les utilisateurs 302 | Toute donnée saisie par un utilisateur devrait être validée dès sa réception, afin que seules des données bien formées et assainies soient traitées par votre API. Cela rendra votre API plus sécuritaire, en plus d'atténuer les erreurs causées par des demandes mal formées. 303 | 304 | #### Définissez des paramètres de demande clairs 305 | Définissez l'aspect d'une demande appropriée à votre API, y compris une limite sur la taille des demandes, le type de contenu, et la plage et le format de tout champ spécifique. Si vous acceptez des chaînes de saisie, envisagez de les limiter (par exemple, en utilisant des expressions normales). 306 | 307 | #### Limitez les interrogations ouvertes 308 | Non seulement les interrogations dynamiques et ouvertes constituent un vecteur de menace dangereux, mais elles peuvent également consommer une quantité excessive de ressources de traitement. Consacrez des efforts dès le début à identifier tous les cas d'utilisation valides des interrogations, et effectuez la conception de l'API afin d'y répondre spécifiquement. Si vous devez permettre aux utilisateurs d'injecter des chaînes d'interrogation ouvertes ou des objets dans une API, faites-le seulement pour des API de données ouvertes, de rapports et de statistiques. Ne permettez jamais d'interrogations ouvertes vers une API contenant des données maîtresses, ni vers des API transactionnelles ou commerciales. GraphQL peut être utilisé à des fins de statistiques, d'analytique et de rapports, mais il ne devrait pas être utilisé pour soutenir des transactions d'affaires. 309 | 310 | #### Faites attention aux caractères de remplacement 311 | Les caractères de remplacement dans les API peuvent être dangereux sur le plan de la performance. Si des caractères de remplacement sont permis, assurez-vous qu'il y a des restrictions sur ceux qui le sont et sur le nombre de paramètres qui peuvent les accepter, afin d'éviter le renvoi d'un volume important de données. Il est préférable de refuser une interrogation contenant trop de caractères de remplacement plutôt que de créer un délai d'inactivité dans votre base de données en arrière-plan. 312 | 313 | #### Ne validez pas trop 314 | Avant de valider les données entrantes, assurez-vous que les hypothèses que vous faites concernant vos données d'utilisateur sont universellement vraies. Par exemple : 315 | 316 | * les noms ne sont pas toujours « Prénom 2e prénom Nom de famille » : [Mensonges sur les programmeurs croient au sujet des noms](https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/) (en anglais) 317 | * Les jours ne comptent pas toujours 24 heures : [Mensonges sur les programmeurs croient au sujet de l'heure](https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time) (en anglais) 318 | * Les adresses de courriel peuvent contenir des caractères étonnants : [Je savais valider une adresse de courriel, jusqu'à ce que je lise le RFC](https://haacked.com/archive/2007/08/21/i-knew-how-to-validate-an-email-address-until-i.aspx/) (en anglais) 319 | 320 | ### Consignez l'activité et la performance 321 | De bonnes mesures constituent la base de bonnes décisions fondées sur les preuves. Les journaux peuvent fournir des renseignements concernant les tentatives d'attaques, faciliter les analyses rétrospectives, évaluer la performance du système et suggérer des domaines d'amélioration pour le produit ou les fonctions. 322 | 323 | #### Définissez les mesures de la performance 324 | Différentes applications mesurent la réussite différemment. Plutôt que d'utiliser les mêmes tests de performance pour chaque API, identifiez vos indicateurs clés de performance avant le lancement, et effectuez la conception d'instruments de mesure qui ciblent spécifiquement ces indicateurs. La latence et le temps de réponse vous fourniront différentes informations sur votre API comparativement à la croissance du nombre d'utilisateurs. 325 | 326 | #### Maintenez des journaux qui ont un sens 327 | Tous les accès aux API devraient être consignés en utilisant les normes de journalisation du secteur (par exemple, le [format commun d'événement](https://help.deepsecurity.trendmicro.com/Events-Alerts/syslog-parsing.html) (en anglais)). Si cela est pertinent, suivez les exigences en matière de journalisation dans [NTI-GO 25.0 Exigences générales en matière de sécurité](https://www.ontario.ca/fr/page/nti-go-250-exigences-generales-en-matiere-de-securite) (sections 3.4.2 et 3.4.3) et [NTI-GO 25.13 Exigences en matière de sécurité pour les applications Web](https://www.ontario.ca/fr/page/nti-go-2513-exigences-en-matiere-de-securite-pour-les-applications-web) (section 2.9). Ces journaux devraient être intégrés à un endroit central et doivent inclure, au minimum, les identifiants du système et les identifiants individuels du client qui fait la demande, ainsi que l'heure système. Assurez-vous de ne pas consigner accidentellement des renseignements confidentiels (p. ex., mots de passe). 328 | 329 | #### Vérifiez régulièrement les journaux 330 | Les journaux des API devraient être vérifiés régulièrement afin de surveiller l'existence de tendances suspectes en matière d'utilisation ou d'accès, par exemple des demandes après les heures d'ouverture, un volume de demandes inhabituellement élevé ou des échecs répétés de validation des données entrantes. Les événements suspects doivent être envoyés au Centre des opérations en matière de cybersécurité de la Division de la cybersécurité du ministère des Services gouvernementaux et des Services aux consommateurs. 331 | 332 | #### Effectuez un audit des accès aux données sensibles 333 | SI votre API fournit des données personnelles ou sensibles, vous devez consigner qui a accédé aux données et à quel moment. Cela est requis pour répondre à des demandes d'accès par l'objet des données, et contribue également à prévenir la fraude ou le mésusage. Consultez votre service juridique pour obtenir les exigences des politiques sur la conservation et de la garde des données. 334 | 335 | ### Optimisez la performance 336 | Pour que votre API puisse répondre aux besoins de tous les utilisateurs, examinez bien la taille de chaque charge et le taux de réponse. La performance de l'API devrait être évaluée périodiquement afin de vous assurer de toujours satisfaire aux besoins d'affaires existants ou projetés. 337 | 338 | #### Surveillez et testez la performance 339 | Il est important que votre API renvoie des résultats de façon rapide et uniforme. Bien que la vitesse ne soit pas la seule mesure qui compte, [une étude de recherche sur l'expérience utilisateur](https://www.nngroup.com/articles/powers-of-10-time-scales-in-ux/) (en anglais) suggère qu'avec un temps de réponse de 0,1 seconde (100 ms), les utilisateurs ont l'impression d'interagir directement avec le système, tandis que des temps de réponse supérieurs à 1 seconde sont perçus comme un ralentissement important. Nous vous recommandons de cibler un temps de réponse d'au moins 200 ms, et préférablement de 50 ms. 340 | 341 | Pour cela, vous devriez constamment surveiller la performance et exécuter régulièrement des tests de performance pour déterminer le temps de réponse et le débit. Voir la section [Effectuez constamment des essais](#effectuez-constamment-des-essais). 342 | 343 | #### Limitez le débit de l'accès des utilisateurs, lorsque cela est approprié 344 | [La limitation du débit](https://apisyouwonthate.com/blog/what-is-api-rate-limiting-all-about) (en anglais) est un bon moyen de gérer la quantité de ressources informatiques requises par une API. Si l'adoption généralisée d'une API est prévue ou si les coûts relatifs au serveur présentent une préoccupation, envisagez de limiter le débit de l'utilisateur en fonction de la fréquence à laquelle il peut lancer un appel à l'API, de la quantité de données qu'il peut demander à la fois, ou du nombre de connexions qui peuvent être actives en même temps. 345 | 346 | La limitation du débit améliore également la sécurité en empêchant une personne malveillante de surcharger l'API en envoyant un trop grand nombre de demandes, par l'entremise d'une attaque par déni de service, tout en gardant le système disponible pour tous les utilisateurs. Si la limite est dépassée, une erreur standard HTTP 429 peut être renvoyée. 347 | 348 | #### Mettez en œuvre la pagination et la segmentation des données 349 | Les API qui exposent d'importants ensembles de données doivent accepter une certaine forme de segmentation des données, tant pour optimiser la performance de l'API que pour offrir une meilleure expérience à l'utilisateur. Voici quelques schémas communs de pagination, avec des cas d'utilisation appropriés : 350 | 351 | * `page` et `per_page` sont plus appropriés lorsque l'ensemble de données n'est pas mis à jour fréquemment et les mêmes données seront probablement renvoyées pour la même référence de page avec le temps, par exemple des données historiques ou de référence. 352 | * `offset` et `limit` sont plus appropriés pour des données fréquemment mises à jour, lorsque les utilisateurs voudront probablement voir des points de données plus anciens (décalés *offset* de) qu'un point de référence donné, par exemple pour sauter les articles de nouvelles que vous avez déjà lus. 353 | * `since` et `limit` sont plus appropriés pour les données fréquemment mises à jour, lorsque les utilisateurs voudront probablement voir les nouveaux points de données ajoutés depuis (since) un point de référence donné, par exemple pour voir le nouveau contenu depuis votre dernière visite. 354 | 355 | #### Appliquez des cas spéciaux aux ensembles de données en vrac 356 | Dans certains scénarios, des API devront rendre des ensembles de données en vrac disponibles entre des systèmes ou au public. Dans ces scénarios, tenez compte des éléments suivants : 357 | 358 | * Les plus petits ensembles de données devraient être retournés dans des formats qui nécessitent moins de temps système (p. ex., CSV ou JSON) que XML. Les pièces jointes comprimées devraient être évitées, surtout lors de l'utilisation d'API externes, car elles peuvent masquer du contenu malveillant. 359 | * Les API de déclenchement amorcent des actions qui nécessitent beaucoup de ressources, lesquelles sont alors effectuées par un autre système. Elles peuvent commencer ou arrêter des événements tels que les transferts gérés de fichiers, ce qui est plus efficace qu'utiliser l'API pour transférer la totalité de l'ensemble de données. 360 | * Les API recherche-et-connexion sont plus appropriés pour indexer des serveurs de fichiers existants. Ces API renvoient des liens vers des fichiers précis, et non le contenu de ces fichiers. 361 | 362 | ### Établissez une politique de mise en cache 363 | Si votre API renvoie des données qui sont souvent demandées, mais rarement changées, vous pourriez mettre en œuvre une mémoire cache de réponse qui stocke la réponse à une demande GET dans une ressource unique pour une récupération rapide. 364 | 365 | Meilleures pratiques en matière de mise en cache : 366 | 367 | * Envisagez l'utilisation de [l'expiration de la mémoire cache fondée sur des clés](https://signalvnoise.com/posts/3113-how-key-based-cache-expiration-works) (en anglais) afin de ne pas servir d'objets périmés 368 | * Assurez-vous que la mémoire cache est surveillée afin de minimiser les objets périmés 369 | * Assurez-vous que le serveur a suffisamment de mémoire pour gérer les charges dans la mémoire cache 370 | * Soyez prudent lors de la mise en cache de données non publiques, afin de ne pas les servir accidentellement à des utilisateurs non autorisés 371 | 372 | ### Documentation 373 | Chaque API doit être accompagnée de documentation concise et à jour qui présente la manière de consommer cette API. Les pratiques suivantes contribuent à s'assurer que les API sont documentées correctement, sans entraîner le fardeau excédentaire associé à la gestion de documentation d'accompagnement. 374 | 375 | #### Documentez les spécifications de l'API et les cas d'utilisation 376 | Votre documentation devrait inclure : 377 | 378 | * les spécifications techniques ou le contrat de l'API 379 | * la manière dont les développeurs peuvent utiliser votre API, y compris la configuration, [l'authentification](#%C3%A9tablissez-une-politique-dacc%C3%A8s-clairement-d%C3%A9finie) et [la limitation du débit](#limitez-le-d%C3%A9bit-de-lacc%C3%A8s-des-utilisateurs-lorsque-cela-est-appropri%C3%A9) 380 | * les renseignements concernant la disponibilité de l'API, [la gestion de version](#utilisez-la-gestion-s%C3%A9mantique-de-version) et la gestion des incidents 381 | * un [point de contact](#faites-conna%C3%AEtre-vos-intentions-nsn-no5) et un moyen pour les utilisateurs de rester au courant des changements prévus 382 | 383 | Un moyen efficace d'aider les utilisateurs à commencer rapidement à utiliser votre API consiste à publier du code qui l'utilise, par exemple des cas de test et des données de validation. Voir la section [Effectuez constamment des essais](#effectuez-constamment-des-essais). Des exemples de code source peuvent être publiés sur le [compte Github de la FPO](https://github.com/ongov). 384 | 385 | #### Utilisez OpenAPI pour les API REST 386 | Utilisez la [spécification OpenAPI](https://github.com/OAI/OpenAPI-Specification) (en anglais) pour les API REST, qui créera une spécification lisible par machine pour l'interface. Il existe des outils ouverts (p. ex., [Swagger](https://swagger.io/solutions/api-documentation/) (en anglais)) qui peuvent alors générer de la documentation lisible par l'utilisateur à partir de cette spécification, ce qui évite d'avoir à créer et à maintenir des documents distincts. 387 | 388 | #### Langages WSDL pour SOAP 389 | Chaque API SOAP doit être accompagné d'un contrat de langage de description de services Web ([WSDL](http://www.w3.org/TR/2007/REC-wsdl20-primer-20070626/) (en anglais)). Le langage WSDL est une spécification lisible par machine qui permet au développeur de l'API pour consommateurs de générer le code pour les consommateurs. 390 | 391 | #### Ne documentez pas trop 392 | En suivant le principe de « [dogfooding](#consommez-ce-que-vous-cr%C3%A9ez) », vous devriez documenter l'API dans la mesure où la documentation vous aide et aide d'autres personnes à utiliser l'API, mais pas jusqu'à ce que la documentation soit susceptible de devenir confuse et obsolète. 393 | 394 | ## Considérations futures 395 | Un des principes sous-jacents au développement agile est que le mieux ne doit pas devenir l'ennemi du bien. Il est important d'habiliter les équipes à fournir un service solide, minimalement acceptable, qui est sécurisé, robuste et évolutif, sans devenir trop ambitieux concernant des fonctions agréables, qui retardent le lancement et empêchent de vrais utilisateurs de tester votre service. Voici d'autres facteurs dont vous devriez tenir compte lors des itérations de votre API et du développement de nouvelles fonctions. 396 | 397 | ### Utilisez un catalogue pour votre API 398 | Toutes les API devraient être publiées avec un catalogue ou un inventaire quelconque. Un tel inventaire peut être un référentiel central de métadonnées et de documentation, un point de contact pour la gestion du cycle de vie pour les développeurs, et un portail de découverte pour les nouveaux utilisateurs. Ce catalogue peut également être intégré avec une passerelle d'API complète qui gère directement le flux du trafic de l'API, fournissant ainsi des capacités supplémentaires de gestion des utilisateurs et des contrôles de sécurité. Consultez le [Magasin des API du gouvernement du Canada](https://api.canada.ca/fr/accueil) ou le [portail des API de la NASA](https://api.nasa.gov/) pour obtenir des exemples de tels catalogues. 399 | 400 | Contactez les Services numériques de l'Ontario pour obtenir de plus amples renseignements sur le statut d'un catalogue des API pour la Fonction publique de l'Ontario. 401 | 402 | ### Définissez une entente relative aux niveaux de service 403 | 404 | L'idéal est que chaque API soit accompagnée d'une entente relative aux niveaux de service (ENS) claire qui définit les caractéristiques suivantes : 405 | 406 | * Heures de soutien (p. ex., 24/7, de 9 h à 17 h, heures ouvrables d'un océan à l'autre) 407 | * Disponibilité du service (p. ex., 99 %) 408 | * Temps de réponse du soutien (p. ex., moins d'une heure, 24 heures, le mieux possible) 409 | * Arrêts planifiés (p. ex., pendant la nuit, une fois par semaine, un dimanche soir sur deux) 410 | * Limite de débit (p. ex., 100 demandes par seconde par consommateur) 411 | * Limite sur la taille des messages (p. ex., < 1 Mo par demande) 412 | 413 | ### Publiez le code source et les tests 414 | 415 | La publication du code source de votre API comme code source ouvert offre de nombreux avantages. 416 | 417 | * Permet à une plus grande communauté de développeurs de repérer des problèmes potentiels avec le code 418 | * Améliore la transparence et l'imputabilité du gouvernement 419 | * Permet à d'autres ministères de résoudre des problèmes semblables sans devoir réinventer la roue 420 | * Contribue à la communauté ouverte, du travail de laquelle le gouvernement bénéficie 421 | * Démontre les compétences techniques de la fonction publique, ce qui contribue à attirer des employés talentueux 422 | 423 | Même si vous n'avez pas l'intention d'ouvrir votre code, c'est une bonne pratique de le développer comme s'il sera examiné par le public. Cela peut souvent fournir facilement une vue d'ensemble de haut niveau qui permet de déterminer s'il y a des manques flagrants en matière de sécurité. 424 | -------------------------------------------------------------------------------- /README-FR.md: -------------------------------------------------------------------------------- 1 | # Création de services numériques connectés : Lignes directrices sur les API 2 | ## Apprenez à créer des services qui peuvent se connecter les uns aux autres et se compléter en utilisant les interfaces de protocole d’application (API). 3 | 4 | Dernière mise à jour : 26 août 2019 5 | Version : alpha 6 | Contact : [digital.standard@ontario.ca](mailto:digital.standard@ontario.ca) 7 | 8 | *Nous commençons à peine à donner vie à ces lignes directrices. Nous vous encourageons à adopter ces lignes directrices le plus possible et de nous transmettre vos commentaires. Vous pouvez nous envoyer un courriel à [digital.standard@ontario.ca](mailto:digital.standard@ontario.ca), ou consulter [CONTRIBUTIONS-FR.md](CONTRIBUTIONS-FR.md) pour obtenir de plus amples renseignements.* 9 | 10 | Contenu: 11 | * [**Lignes directrices sur les API**](Lignes-directrices-sur-les-API.md) 12 | * [Lignes directrices en matière de contributions](CONTRIBUTIONS-FR.md) 13 | * [Licence](LICENCE-FR.md) 14 | 15 | ## Traduction anglaise 16 | 17 | Consultez [README.md](README.md). 18 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Building connected digital services: API Guidelines 2 | ## Learn how to create services that can connect to and build on each other by using Application Programming Interfaces (APIs) 3 | 4 | Last update: August 26, 2019 5 | Version: alpha 6 | Contact: [digital.standard@ontario.ca](mailto:digital.standard@ontario.ca) 7 | 8 | *We’re in the early days of bringing these guidelines to life. We encourage you to adopt as much of the guidelines as possible, and to share your feedback with us. You can send us an email [digital.standard@ontario.ca](mailto:digital.standard@ontario.ca), or see [CONTRIBUTING.md](CONTRIBUTING.md) for more details.* 9 | 10 | Contents: 11 | * [**API Guidelines**](API-Guidelines.md) 12 | * [Contribution guidelines](CONTRIBUTING.md) 13 | * [License](LICENSE.md) 14 | 15 | ## French translation 16 | 17 | Please see [README-FR.md](README-FR.md). 18 | --------------------------------------------------------------------------------