With more than 12,000 agencies having datasets to provide and over 60 million people that need their digital services, the Italian government’s digital transformation team had a huge challenge ahead of them. In order to provide great digital services across the country and the European Union, reliable integrations are no longer a nice-to-have; it’s an absolute need. The entire system can get bottlenecked if digital services in agencies don’t match up and a service gets blocked.
That demand for seamless and consistent integration means that if even one API fails, major trouble is on the horizon. We spoke with representatives from the Digital Transformation department of the Italian government about how they tackled this problem. Their team worked on designing the API ecosystem for the entire country, particularly defining guidelines that all government agencies and their suppliers must follow regarding API creation. Interoperability is the name of the game, and API style guidelines were the key to winning that game.
The Challenge
The digital transformation team identifies blockers and addresses these blockers on the technical side. On the organizational side, they also address any administrative issues that may hinder the creation of digital services.
Their work could involve integrations from a single API or multiple APIs from different agencies, all to enable a single digital service for one citizen. Creating a digital platform that streamlines the interactions required by the many agencies, providers, and suppliers consuming APIs is challenging.
The Government’s strategy was to create guidelines that facilitate collaboration between two or more public administrations by means of technological solutions that ensure interaction and exchange of information without implementation constraints. Specifically, the resulting style guidelines would be used to promote the development of consistent digital interfaces (APIs) and the application of secure design practices.
The Solution: Stoplight’s Spectral Tool
To accomplish this incredible feat, the digital transformation team turned to Stoplight’s open-source linting tool, Spectral, to support these guidelines. Spectral is open source but is also baked into the Stoplight Platform tool, giving you real-time feedback wherever you design APIs and providing guidelines around API governance to enable standardization and consistency.
The first thing the team thought about was how an organization without deep technical knowledge can rely on suppliers and ensure the supplier is doing the right work. They started looking for tools to solve this for testing APIs. According to the project page, there were different tools, but they liked Spectral. This was because it does not need to employ infrastructure and can be tested. Spectral agencies don’t need to share their API specs to validate.
The second reason Spectral drew their attention was that they could use YAML with it instead of relying on JavaScript. Sometimes, using Javascript endangers operations by running arbitrary code on their infrastructure. Now, there are more Javascript options than before, but even now, as their team aims to provide some rules that require code, if they don’t need to, then they avoid using Javascript.
The more YAML and JSON work the team did, the easier it is for other implementers to adopt. This is because they can easily clone and deploy their repositories by themselves and have a direct distribution point on the web. They benefitted from having a single distribution point for the ruleset, which is the Github Project website, where all their agencies can go to grab the information they need.
Since implementing their guidelines, they have seen many agencies and suppliers adopting them and utilizing that data. Utilizing Spectral rulesets has created better communication and collaboration between agencies and suppliers, positively impacting all Italian suppliers.
Previously, only the larger agencies and suppliers were able to deeply understand the API guidelines. Still, their team was proud to share that municipalities and even smaller agencies are increasing the guideline compliance to write secure APIs.
The support tool his team created, called the “OpenAPI Checker,” is a verifier — currently in a beta version — which analyzes the specifications of a REST API and ensures it’s compliant with the Representational State Transfer architectural style.
What to Consider When Creating Guidelines For Government Agencies
The digital transformation team was tasked with identifying best practices and working with multiple stakeholders across the organization to support regulatory agencies enabling a streamlined API creation and consumption process.
The problem they were aiming to solve was far past a technical problem; it also includes organizational and legal issues involving multiple stakeholders from all departments.
Sharing Private Information Securely
Enabling these standards and guidelines was made even trickier when you take into account that a government agency or anything in the public sector needs to be able to manage private citizen information and transfer that data safely among databases via APIs.
Agencies need to trade that information without the content of the citizen being known, so they have to work through the regulatory framework and the legal work to utilize that data properly. Dealing with sensitive information makes following style guides for API creation all the more important!
Dealing with Semantics
When creating the guidelines, their team did all the technical stuff first. But, then it came down to the organizational issues too. Now, they are working to address semantics, and using OpenAPI validators for that would ease things.
And when dealing with agencies and suppliers that span far and wide and work within the entire European Union, the answer to whether they all have the same semantics is–absolutely not!
The example their team used in this presentation was in reference to the term “name,” which in some cases can be the current given name and in others the birth name The semantics and naming conventions across different public services are not always the same, so API providers have to account for these differences. Ensuring a coherent understanding across all public services interacting via APIs means they had to build vocabularies to disambiguate terms overloaded with different meanings.
Another example the team came across was the semantics around what the term “recovered from COVID” meant across different agencies and in time. The issue is detailed in this 2020 paper (in Italian). Was it one test or two? What kind of test did they take, and how long was the recovery period? Since there can be different meanings, you can’t correctly provide an API if the purpose is different because the API does not provide the payload that the consumer intends.
The Importance of Interoperability
In the end, everything the Italian digital transformation team does has to operate on a level of interoperability, primarily since they exchange information with the larger European Union.
For example, if one wants to move to another country, and that new country has different guidelines around its digital infrastructure, integrating APIs will be more expensive. You need a solid API to connect the various systems.
Interoperability is critical because people in the countries should be able to get services across Europe regardless of where they are, and Italy is working with other countries to increase the number of cross-border services and achieve this goal. Still, there is always more work to be done and new horizons to tackle.
If you want to try Spectral for yourself, you can download it here. You can also check out the full suite of API design tools in Stoplight Platform if you’re interested in leveraging built-in style guides, using public style guide templates, and up-leveling your governance strategy for your own API program. For more information on the Italian government’s Digital Transformation team’s work, check out their article in Medium.
