As part of co-operation with apidays conferences, and apidays Helsinki 2020, a joint online event was held in collaboration with Joint Research Centre of the European Commission on public and private sector co-design on API development.
After presentations by public sector organizations from around Europe, a panel discussion summarized and aimed to answer the questions coming from these public sector organizations.
Private sector seasoned API experts Alan Glickenhouse (IBM) and Marjukka Niinioja (Osaango, panel chairperson), as well as Lorenzino Vaccari (European Commission, JRC consultant) discussed API-related questions presented by the public sector speakers in part II as well as topics brought on by the audience.
Panel concentrated on questions related to lifecycle management, discoverability, API design and security.
How should you handle API change management?
Questions for the panel:
- How should major API changes be handled and ensure backward compatibility?
- How should API consumers be helped to be prepared for these changes and support them to upgrade their application consistently?
Glickenhouse: Try to reduce as much as possible the use of versioning, and avoid breaking changes. Best practices to create backward compatibility must be used. Try to have consumer vs. provider-oriented APIs. Try to expose the minimal and essential set of things the consumers ask for, to limit the access to the backend system. Also, try to have loosely coupled external systems for the backend. This way changes to the backend systems have the lowest impact on the external APIs.
You will occasionally still have breaking changes. Remind potential consumers about the policies and migration times for new versions in your terms and conditions when they subscribe. You will potentially have multiple versions available of the same API at the same time, and when version 2 becomes available you will want to stop any new subscribers from subscribing to version 1, even if it’s still available for some time to the existing subscribers. Notify registered users of the previous version that there is now a new version available and try to “sell” them how much better the new version is compared to the others. Tell them also how long you will give them time to move to the new version. In your API management analytics, you should see who is still using the old version and you should periodically remind them to switch to the new one. But sometimes that last user is your most important user, so sometimes you just need to help them how-ever you can.
Niinioja: This is a problem in the private sector, too, and the time to support previous versions varies a lot according to the industry, from some months to a few years.
Vaccari: In the case of Open Data it is a challenge for governments to maintain their datasets published in an open data catalogue aligned with the backend datasets. The risk is that after the publication of the datasets, they are left unattended. In the meanwhile, the systems providing that open data evolve. When users are using the datasets, they find out that they are not up-to-date or working because of the changes. When users bring issues in the data up to the government, they get answers like “this is not the correct version of the data, the correct version is in our systems”. Thus, we must put a lot of attention in managing correctly the API versioning, especially for the ones that are exposing datasets. API versioning, will then be very helpful in making available the last current version of the dataset, too.
Niinioja: This is a typical problem not even related to the API versioning, but to the lifecycle of the data, the APIs are handling. A great example is postal codes, which are often provided in various open datasets without a clear information of when these codes change, or who is the actual “owner” of that data. Sometimes the public funding for an open data project stops and after that the data is never updated.
Vaccari: The situation is improving, many times exactly because of APIs. In many open data catalogues, you need to now provide versioning information for both the API and the data it handles. This is even more important now that there is the recent European Union Open Data directive that demands six high value areas of public data to have APIs. With these datasets the versioning is highly important, because they will support the digital transformation of the whole EU society.
Part 2 : What is the impact of distributed architecture to API lifecycle?
