Audit: New Project

Complete the audit questions below. Your progress is saved automatically.

Architecture

Design

Usage

Logs

Architecture

AR01

Use Event Driven Architecture to avoid polling madness and inform subscribers of an update

Use Event Driven Architecture to avoid polling madness.

Compliant

Use Event Driven Architecture to avoid polling madness and inform subscribers of an update

We often notice that applications, in order to refresh their data, make very frequent requests to APIs. This causes an important workload and we increase the computing resources to absorb this load in order not to penalize the other users. The best practice is to use an event-driven architecture in order to receive a notification when a piece of information is modified to avoid making regular useless requests. But the data contained in the event must be precise to be sure to avoid a system making a request to retrieve an unused data.

AR02

API runtime close to the Consumer

Deploy the API near the consumer

Compliant

API runtime close to the Consumer

It is not uncommon to find that APIs are deployed in locations that are not selected in relation to their consumers. This results in not only a degraded user experience in some cases, but also a greater demand on the network to route requests sometimes to a region on the other side of the world. Good architecture practices therefore recommend deploying APIs, and services in general, as close as possible to the consumers. Also, if possible, prefer a deployment in several locations with geo routing (aka. position based routing) to the closest instance to improve response times and reduce the number of kilometers traveled by requests.

AR03

Ensure the same API does not exist *

Ensure only one API fit the same need

Compliant

Ensure the same API does not exist *

It is often noticed, especially in large information systems, that an API with the same purpose and objective can exist several times. These duplicate APIs, in addition to creating confusion in the minds of users, consume additional resources instead of pooling them for a unique API. It is recommended to use the data catalog to make sure that the API you want to develop does not already exist. If an existing API covers part of the functional scope, it may be worthwhile to contact the producer as it may be possible to plan an evolution of the existing system rather than creating a duplicate.

AR04

Use scalable infrastructure to avoid over-provisioning

Compliant

Use scalable infrastructure to avoid over-provisioning

Depending of your infrastructure, used scalable runtime fit to your activity

Design

DE01

Choose an exchange format with the smallest size (JSON is smallest than XML)

Prefer an exchange format with the smallest size (JSON is smaller than XML).

Compliant

Choose an exchange format with the smallest size (JSON is smallest than XML)

One of the structuring questions when designing an API is the selection of the exchange format to use. If the choice is often made by technical constraints or personal affinities, the durability aspect is also to be taken into account. Indeed, there are exchange formats that are heavier than others. For example, JSON is smaller than XML. The second format will therefore have a stronger impact on the network, the computing and the storage. In the interest of sustainability, we recommend to use a lighter exchange format to reduce the bandwidth consumed for the requests, the compute and storage resources consumption used to process and store the payloads.

DE02

new API --> cache usage

Use cache to avoid useless requests and preserve compute resources.

Compliant

new API --> cache usage

The use of a cache has become common in computer architectures to store frequently used information on a fast storage. In addition to improving the response time of APIs, and therefore the consumer's experience of the service, it also saves computational resources by avoiding executing the same query on the same data multiple times. It is recommended to place a cache in front of each brick of an architecture returning data (API, database, frontend application, ...) and close to the users to preserve compute resources and improve performances of the API.

DE03

Existing API --> cache usage efficiency

Use the cache efficiently to avoid useless resources consumtion.

Compliant

Existing API --> cache usage efficiency

DE04

Opaque token usage

Prefer opaque token usage prior to JWT

Compliant

Opaque token usage

One of the structuring questions when designing an API is the selection of the token type to use. If the choice is often made by technical constraints or personal affinities, the durability aspect is also to be taken into account. We can note that an opaque token, in addition to improve the security, is smaller than a JWT token which will have a stronger impact on the network, storage and compute resources. In the interest of sustainability, it is therefore recommended that a lighter token type be preferred in order to reduce the bandwidth, compute and storage resources consumption.

DE05

Align the cache refresh with the datasource **

Align cache refresh strategy with the data source

Compliant

Align the cache refresh with the datasource **

DE06

Allow part refresh of cache

Allow a part cache refresh

Compliant

Allow part refresh of cache

When configuring a cache, it often happens that the data refresh policy (TTL) is not synchronized with the data life cycle. In this case, the cache is not fully efficient because the data is expired too early or too late. It is necessary to provide an expiration policy adapted to the data refresh cycle and to allow partial expiration of the cached data in order to be as efficient as possible on all the processed data. To optimize the cache as much as possible, it is also possible to build an architecture where the source of the data notifies, via an event, the cache of the expiration of a specific data.

DE07

Is System, Business or cx API ?

Use Business & Cx APIs closer to the business need

Compliant

Is System, Business or cx API ?

Sometimes the data returned by an API is structured in such a way that, in order to have all the data the user needs, it is necessary to make several requests to the same API. This has the consequence of increasing the consumption of bandwidth and computing resources, for the API that has to process several requests, and of bandwidth. Therefore, it is important to provide a consistent data structure regarding the use of the API. This client-centric best practice prevents the consumer from having to perform multiple queries to retrieve all the information they need.

DE08

Possibility to filter results

Implement filtering mechanism to limit the payload size

Compliant

Possibility to filter results

It often happens that the implementation of filters in the APIs allowing to return only the necessary data to the consumers are forgotten or not efficient. This forces API consumers to make generic requests that retrieve unnecessary amounts of information, resulting in overconsumption of bandwidth and storage. It is recommended to design and implement filters that allow the user to limit the amount of data returned to optimize network and storage consumption.

DE09

Leverage OData or GraphQL for your databases APIs

Leverage OData or GraphQL when relevant

Compliant

Leverage OData or GraphQL for your databases APIs

It is quite common to see API backends built to allow database integration. In some cases, these systems are completely redeveloped with data schemas that are not adapted to the usage. This forces users to perform several queries, often complex, to retrieve all the data they need. To build an interface to a database, it is recommended to rely on OData or GraphQL technologies that allow consumers to perform complex queries.

DE10

Redundant data information in the same API

Avoid redundant data information in the same API

Compliant

Redundant data information in the same API

To reduce the risk of misinterpretation caused by data duplication and streamline the communication process. Each piece of data should be essential and distinct to the operation at hand. Duplicate data can lead to confusion and misinterpretation, as consumers of the API may not be able to determine which data points are relevant or current. Ensuring data uniqueness within API responses prevents such misunderstandings and simplifies data parsing and handling. By enforcing this rule, we ensure that each API response is concise and that the data provided is a clear and accurate representation of the requested information. Redundant data inflates the payload, increases processing time.

DE11

Possibility to fitler pagination results

Implement pagination mechanism to limit the payload size

Compliant

Possibility to fitler pagination results

Implement pagination to limit which data are returned by the API (send just the data the consumer need) using for exemple "next", "skip", "top", … Check payload log to validate if pagination keywords are used

Usage

US01

Use query parameters for GET Methods

Implement filters to limit which data are returned by the API (send just the data the consumer need).

Compliant

Use query parameters for GET Methods

Optimize queries to limit the information returned to what is strictly necessary. It is often observed that requests made on APIs are not precise enough, which returns a volume of information greater than necessary. This results in increased bandwidth consumption during exchanges. The best practice is to create precise requests that return, as much as possible, the strictly necessary information, thus avoiding the transfer of useless information. This rule is linked to DE08 : “Implement filters to limit which fields are returned by the API ”

US02

Decomission end of life or not used APIs

Compliant

Decomission end of life or not used APIs

It often happens that the APIs of an information system are rarely or no longer used but are not decommissioned. This leads to the consumption of computing resources for useless or obsolete components. It is important that the decommissioning phase is also treated as part of the application life cycle in order to free up allocated resources. In the case of a rarely used API, a root cause analysis should be performed prior to decommissioning to understand why it is not used more often.

US03

Number of API version <=2

Compute resources saved & Network impact reduced

Compliant

Number of API version <=2

Have a good lifecycle management of API by reducing the number of API version on production The value of 2 release can be challenge depending of your context. Less version permit to have less technical debt.

US04

Usage of Pagination of results available

Optimize queries to limit the information returned to what is strictly necessary.

Compliant

Usage of Pagination of results available

Some request can return a huge volume of data. We can optimize the response by using pagination. A control can be used to check some keywords like next, skip, top, etc … This rule is linked to DE11 : “Availability of pagination”

US05

Choosing relevant data representation (user don’t need to do multiple calls) is Cx API ?

Choose the correct API based on use case to avoid requests on multiple systems or large number of requests. Refer to the data catalog to validate the data source.

Compliant

Choosing relevant data representation (user don’t need to do multiple calls) is Cx API ?

US06

Number of Consumers

Deploy an API well designed and documented to increase the reuse rate. Rate based on number of different consumers

consumers

Number of Consumers

Deploy a well designed and documented API to increase the reuse rate and improve time to market. Based on documentation provided in the API Portal. The more accurate the documentation, the easier it will be for consumers to understand and use the API. This indicator is a percentage rate.

US07

Error rate

Monitor and decrease the error rate to avoid over processing

Error rate

Decrease the error rate (results different from 2xx) to avoid over processing. Depending of your context, you can focus on 4xx or 5xx errors, or both. One of objectives of this rule is to improve the quality of requests (fill all required fields, or better control of contract,etc… ) and improved the response if we have to many errors due to tech

Logs

LO01

Logs retention

Align log retention period to the business need (ops and Legal)

Compliant