Table of Contents
- Executive Summary
- API Standardization
- API Documentation Standards
- API Versioning Standards
- API Naming Standards
- API Message Format
- API Security
Executive Summary
Broadly speaking, the API strategy and standards for Payments Canada needs to address some simple characteristics of the development community at large. These critical characteristics are:
- Consistency – consistency within the tools, interfaces and models not just across the catalogue of APIs but also in comparison to the industry at large. Picking methods and standards that are already being rolled out by Payments Canada’s industry partners will make the uptake of its APIs that much simpler.
- Stability – infrastructure needs to be designed and deployed to ensure the accessibility and availability of APIs at all times.
- Performance – APIs should be delivering a published set of performance metrics that meet the threshold of the business requirements.
Whether the APIs are being developed for internal, closed community or open release to the public, these aspects will cultivate trust and understanding among our development communities. This document supplies the detailed options and selections made to establish the standards that will be applied to API development to address the Consistency aspect above. In summary, the following API design standards are being adopted for Payments Canada:
- API Interface Standard: RESTful API
- API Hypermedia Format: JSON
- API Documentation Standard: OAS 3.0 (deprecated: Swagger 2.0)
- API Prototyping and usage definition tools: Postman
- API Security: OAuth 2.0
- API Message body format: ISO 20022 JSON messages or proprietary JSON messages
- API Versioning Model: Media Type Method
- Resource naming best practices are also provided
Using these resources and standards, Payments Canada will be able to publish a set of consistent and stable API interfaces that are in line with existing standards and are aligned with the standards being adopted within the banking industry.
API Standardization
Payments Canada API Interface Standards
There are a variety of API interface standards available to choose from that have been created throughout the industry over the past 40 years.
The API Interface standard for Payments Canada will be focused initially on the RESTful model, with a strong preference to constrain the operations of APIs across all interfaces to a single request/response model using the RESTful API specification over the HTTPS-secured HTTP protocol.
This will drive a resource-bound implementation of APIs that can leverage a microservice or orchestrate several microservices to complete the associated resource request.
At Payments Canada, we choose to follow RESTful design patterns. You can find more details on these patterns on Microsoft's website, available at https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design.
Payments Canada Hypermedia Standard
With an established standard for building RESTful APIs, there needs to be a set standard for the hypermedia format of the messaging embedded in those API interfaces.
Payments Canada will look to adopt the JSON:API Hypermedia format standard where it makes sense to align with the most popular industry API Hypermedia usage. This will make it easier for development teams to understand and define their API requests.
Overview of API Hypermedia Formats
The following table elaborates on the various Hypermedia formats available and the acceptance, pros, and cons of each:
|
Model |
Description |
Pros |
Cons |
|
JSON:API |
Designed to ensure separation between clients and servers, while also minimizing the number of requests without compromising readability, flexibility, or discovery. |
|
|
|
HAL |
HAL incorporates 'CURIEs', a feature that makes it unique and allows for the inclusion of documentation links in responses – they are tightly coupled to the link name. HAL is one of the most supported and most widely used hypermedia specs and is surrounded by a strong and vocal community. |
|
|
|
Collection+JSON |
Collection+JSON is a JSON-based read/write hypermedia-type designed to support the management and querying of simple collections. It is based on the Atom Publication and Syndication specs, defining both in a single spec and supporting simple queries through the use of templates. |
|
|
|
ProtoBuf |
A more advanced and compact message method from Google that can be substituted for JSON |
|
|
API Documentation Standards
As with other aspects of APIs discussed above, there are a variety of methods for documenting and representing APIs which need to be considered.
Payments Canada API Documentation Standard
All API services need to reside in a repository such as GitHub or Bitbucket. Here are the base elements of what is contained within each repository:
- OpenAPI - A JSON definition for the surface area of an API, including the request, responses, and underlying schema used as part of both.
- Postman Collection - A JSON Postman Collection that has been exported from the Postman client after importing the complete OpenAPI definition, and fully tested.
The goal is to establish a complete index of the APIs using OpenAPI and make it available in our developer portal, including the postman collection when applicable.
API Documentation Methods
Of the many API documentation and specification formats, we've selected OpenAPI Specification (OAS3) which is one of the most popular API documentation methods. There is a wealth of tools available to generate code and documentation which gives the ability to present specs in a standardized manner.
- Pros:
- Widely adopted
- Integrated in many tools and platforms for APIs
- Follows JSON formatting
- Language Agnostic
- Cons:
- Lacks advanced constructs for metadata
API Versioning Standards
Another area where a range of standards have proliferated in the industry is around how you identify and manage API versions. Your API Governance and Lifecycle should be able to take care of the creation of new versions, the time to live of those APIs and the retiring process of various versions of an API, but the version of the API itself is usually embedded somehow into the interaction model of the API itself such that it is fairly clear, by looking at the request or the URI, what version of that API is being used.
Payments Canada API Versioning Standard
The current Payments Canada versioning method is the Media Type accept header method. This allows the consumers of the API to control the content version with their request.
API Versioning Methods
|
Method |
Description/Example |
Pros |
Cons |
|
Media Type |
Customization of the 'Accept' media type header to include the version of the API: |
You can version directly at the resource level (preserve your URIs between versions) This is the closest to the original RESTful specification Better for Proxy Caching |
Harder to test as the versions are not shown on the URL You will need something else than just a browser (i.e. API Store or developer tools) to explore the different versions They distort the HTTP headers’ purpose: clients will need to know the media type for each resource and request the same one throughout their use of your API to ensure their code continues to function normally as you push out new changes. |
|
(Custom) Headers |
Creating header-specific versioning content in the API request: |
Preserve your URIs between versions (because you do not add any version information to the URI) Cleaner looking than the URI versioning method |
If you are already versioning resources with this technique, versioning the API as well can lead to a hard-to-manage configuration |
|
URI |
Different versions of the API will take a different URI path |
The most common method currently in use by APIs today It allows exploring different versions with just a browser. (Enables visual identification of the version being requested) Easy to use/understand Better for Client caching Can load balance versions separately |
It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version) |
|
Domain |
Embeds the API Version into the domain name of the URI instead of the URI string: |
The same pros as the URI method |
Same cons as the URI method, plus users may have to change their security settings to be able to make calls to this new version |
|
(Request) Parameter |
Use a parameter within the URI string to identify the version to be used: |
This is mostly indicated for JavaScript API (CORS-enabled APIs) Just like the URI versioning allows visual identification Can be optional (if no parameter is specified, the last version will be provided) |
Mixing resource versions with this type of API versioning can get very messy |
|
Date |
The initial request to the API sets that point in time via a timestamp to become their version reference until they choose to manually move the date up. Essentially the newest version of the API as of or prior to the timestamp. |
Allows shipping new API features without changing an endpoint. Being able to easily see which customers are using which versions of the API |
It’s a bit complex to implement Makes traceability of what has changed more difficult Dev needs to understand whether the timestamp is compilation time or the timestamp when the API was released) |
API Naming Standards
As mentioned earlier in the document, REST’s primary data representation is called a Resource. Having a strong and consistent REST resource naming strategy will prove to be one of the best design decisions in the long term. Since RESTful APIs operate within the HTTP protocol, the resources are cataloged using a Uniform Resource Identifier and are presented in the same format as a web address i.e. payments.ca/resource/item.
A resource can represent a single item or a collection of items. For example, “accounts” is a collection resource and “account” is a single-item resource. We can identify the “accounts” collection resource using the URI “/accounts”. We can identify a single “account” resource using the URI “/accounts/{accountId}”.
A resource can also contain a sub-collection of resources. For example, the sub-collection resource “accounts” of a particular “customer” can be identified using the URI “/customers/{customerId}/accounts”. Similarly, a single resource “account” inside the sub-collection resource “accounts” can be identified as follows: “/customers/{customerId}/accounts/{accountId}”.
REST API designers should create URIs that convey the REST API’s resource model to its potential developers. When resources are named well, an API is intuitive and easy to use.
Use nouns to represent resources
RESTful URIs should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties as verbs do not – like resources have attributes. Some examples of resources are:
- Users of the system
- User Accounts
- Network Devices etc.
and their resource URIs can be designed as below:
- https://appname.payments.ca/device-management/managed-devices
- https://appname.payments.ca/device-management/managed-devices/{device-id}
- https://appname.payments.ca/user-management/users/
- https://appname.payments.ca/user-management/users/{id}
To make it even clearer, resources should be divided into four simple archetypes or categories: document; collection; store; or controller, a resource should then always be assigned to one of these archetypes, and its naming convention used consistently. For the sake of uniformity, resist the temptation to design resources that are hybrids of more than one archetype.
API Message Format
Selection of the API messaging format is critical to the success of the tooling, security and integration of the APIs with the rest of Payments Canada’s infrastructure.
ISO 20022 Implications on API Messages
At present, the ISO 20022 messaging formats for payments are rendered in both XML XSD format and ASN.1 format. The ASN.1 format is good for older EDI interfaces, and the XML formats are aging rapidly. We need to keep in mind that the ISO 20022 messages are meant to be format agnostic and that the renders available from ISO are published as guidelines and examples. Tooling for developing and publishing ISO 20022 is also designed to output in XML schemas.
While the XML schemas may be largely easier to follow and understand, the format is too bulky and too hard to validate quickly in line with API-style operations. The Tooling for APIs is moving forward faster than the tooling for ISO 20022. Thus Payments Canada will look to provide all of their ISO 20022 messages for Canada in a variety of formats for simplified conversion and adoption of the messages. The tools developing the messages will provide the base XML schemas as the reference point against the published standards from ISO. This will then be converted into a JSON Schema and where necessary we will also publish the ProtoBuf message schema for any gRPC-based APIs that are implemented.
API Security
Authorization & Authentication
We leverage OAuth 2.0 where possible. OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This specification and its extensions are being developed within the IETF OAuth Working Group.
SSL
We require the use of SSL for all API calls.