Maximizing public sector Web APIs


During Christmas holidays (which still continues for me) I began to think of overall framework for utilizing public sector web APIs. The thoughts are rough and full of holes but I’d still say that it begins the discussion which we haven’t had in Finland. The Ministry of Finance has done a good job in nailing down first three views to national services:

  1. consumer/citizen view,
  2. company view and
  3. official (public sector employees) view.

Those views are entry points for various services in national service architecture. When the views are in place, it will be a huge leap forward since now all services are scattered around and there is no unified access point. In the future services will remain scattered but will be gathered under one umbrella.

What bothers me is that there has been only shallow discussions about “developer view” or as I prefer to say “co-operation view”.

Public sector web APIs will be in more crucial role in the future. The amount of open data grows steadily and focus is now turning more to APIs from data sets (blobs). Latest example of this tendency towards APIs is about to be opened REST API from which anyone can get company information in JSON format. The API is provided by Finnish Patent and Registration Office.

Anyway, here’s a few thoughts to discuss. In the model open data APIs are not forced inside the same pipeline with sensitive data (such as digital identity) which will be accessed via X-Road (SOAP driven). I see no reason to force open data APIs to be put inside more restricted and rigid X-Road since open data is…hmmm..well…open.

We need co-operation view

What we need is single point from where developers can access the information about APIs and co-operate with the API providers. In the future we need to utilize open data more in service development and experience. Therefore it’s logical to put open data API information along side with restricted APIs (X-Road managed).


The framework should be in government control. The service must also have co-operation manager. One option where this kind of service could be placed is Valtori. Developers (most common API users) make up the community of users that build apps by using your APIs. API providers are service provider who build, maintain and develop various APIs, which can be utilized via X-Road and directly.

Co-operation portal features

App developers use the portal at least

  • to find APIs (easily)
  • to find stories how different APIs are used and solve problems
  • to learn about available APIs through an API console or/and documentation,
  • to register an account on the portal,
  • to register apps that use your APIs,
  • to interact with the developer community and API providers, and
  • to view statistical information about their app usage on a dashboard.

Since the apps or services would be registered in the portal, new services could be spotted here and raised to other views for consumption: consumer/citizen view, business view and official (public sector employees) view).

API Provider teams create portal content, make their APIs available to app developers, provide API documentation, and provide a mechanism for developers to register apps and obtain API keys.

Best way to promote your API is to get good peer reviews from developers. They are your customers.

Developers are no different from other human beings. Consumers trust peers in selecting hotel for holiday, developers trust peer views more that your sales pitch in evaluting your API. Besides providing marketing channel for new apps we can promote good APIs as well.

Co-operation view or portal should enable easy API discoverability. Finding needed APIs should be based on same logic that we use Google to find information. Using categories has shown the limitations in and a global community of API ambassadors has started to build open source engine for “API Google” called “”. is an experimental API Search service to help discover APIs on the web. The service uses the APIs.json proposed discovery format. The Finnish API:Suomi community is involved in that and will rampup “Finnish API Google” during 2015.

The API providers would add their APIs to service either by hand or via automated logic which would be build on engine. Developers would provide feedback and use the services.

Management: The portal must also have some sort of rate limiting and access management features based on groups and individuals.

X-Road security server should automatically provide access rights for each user to the portal. It should also list newly added APIs

Rest of the services (mostly open data APIs) should use similar group based rights management which might enable even organization level rights distribution. In other words app or developer belongs to an organization and rights to access APIs are tide to the organization.

Identifyind API user is needed even with open data APIs.

Some developer might make a loop error in code and make pull or push request 10 000 a second and flood the API. In those cases rate limiter should also kick in, but API provider should have ability to identify bad behaving app and close the access to API and automatically notify app owner about the situation.

Currently open data APIs are mostly about pull. Developers are pulling information from APIs. In those cases API key based identification is enough. Often developer pulls information from multiple sources and combines the data thus creates value to the end-user. We do not need to stop there.

In the future role of open data push APIs will increase. The role is changed from consumer to prosumer.

In push enabled APIs (could be the same with pull API) app is able to push data sets back to API provider. In those cases user (and the app) mostly likely needs to be identified in more details and strictly that in pull. In those cases we could use simple SAML2 and OAuth 2.0 authentication. The more strict identification would be possible to use with pull APIs as well. The API provider would define the level of authentication for their APIs. This kind of SAML2/OAuth based authentication solution is already in proof of concept phase in EduCloud and will mature to production level during 2015. From there it could be adopted to this portal as well. In other words, we want tiered access control.

Sandboxes must be one feature of co-operation portal. Developers must have opportunities to test APIs with authentic data and features.

One option for co-operation portal is to start with Liferay. Other options must be seeked after and evaluated with the community.