What is an open API?

January 6, 2020
Marjukka Niinioja

In this blog, I will highlight views on the openness of APIs. The views are based on the discussions in the spring 2020 of a Finnish working group. The working group was set to update a Finnish definition made some years ago of an open API. The definition was originally made from the public sector and general openness point of view. Now we wanted to make it more international and private sector compatible. The working group has members from three associations: Open Knowledge Finland (OKFI), Center of Open Source Systems (COSS) and Technology Finland. This text does not represent the opinion of the working group as such. Yet, its purpose is to open up the points of view that we have discussed. We want to continue the debate on the subject, both nationally and internationally.

These discussions in late spring were attended by Mika Honkanen (OKFI), Marjukka Niinioja (COSS) and working group’s volunteers Arvi Leino and Tuukka Hastrup. Each spend a considerable time working with APIs in their day jobs. Other participants have also made a strong contribution to the work of the working group, especially Antti "Jogi" Poikola from Technology Finland and Martin von Willebrand.

It is very demanding to establish an unambiguous definition of an open API. The discussion quickly turns into a value debate and a setting of objectives instead of a 'dictionary definition'. In English the word Open API has had a very different background and purpose than, for example, open data or open source concepts.

You get what you order. Do you want the most open API to be used by a the widest range of consumers producing an impressive result? Then you need to pay attention to providing and acquiring the API. Especially if you order development work, firmware or technology that includes APIs. The terms of the contract therefore play a key role in the openness of APIs. At least in Finland, the current broadly used standard public-private contract terms deal with APIs in a rather limited way.

The needs of public sector and businesses driving openness may sometimes be seen as contradictory. We noticed an assumption that only public sector should be worried about charges and vendor locks. Yet, we found a common tune. We started to work on the openness of the API in relation to the objectives of the benefits of openness.

We found, through various examples, that there were many different aspects. We had to go back to why open data, open source and open API are very similar on the one hand and very different on the other.

This blog tries to summarize the complexity of the discussions and open APIs. In addition, I have included some examples and reflections by my team at Osaango as we worked with public and private sector ecosystems in platform and datahub projects in spring 2020.

At the end, some basic concepts have been opened. These are discussed more broadly in the book API Economy 101 (Moilanen, Niinioja, Seppänen, Honkanen, 2019), including the issues related to the entire open API and related case studies.

An API in this case is the Application Programming Interfaces (APIs) used over the networks (in particular the Internet) and the resources transmitted through them must provide clear benefits to the provider, and a value proposition for the consumer.

Why choose an open API?

In general, the openness of APIs aims for

  • cost-effectiveness,
  • the speed of development and change,
  • ease-of-use and, in particular, the emergence of a network impact, and
  • the creation of an ecosystem with the same objectives,
  • increasing market share (companies)

An open API is used to reach the widest possible range of consumers

There are several ways to achieve widespread use. One way is by standardizing the API, which may be a slow process. Another option is to create a so-called de facto standard. This means ways to ensure that the API is adopted by a large and growing group of consumers.

Only by implementing an error-free, and sufficiently well-functioning API its use can be expected to increase. In addition, to get the API widely used it needs the same things as open source software:

  • Open team of developers
  • Open procedure for reporting development ideas, errors and support requests
  • Transparent roadmap
  • The possibility to influence the decision-making in development.The more open an API is the better it fills these requirements, too:
  • Adequate level and promise of service
  • A common technical implementation of the API;
  • Publicly available standards-based API description and other documentation, and
  • Comprehensive marketing and communication so information about the API reaches potential consumers
  • Ideally, the API documentation should be published so that viewing it or assessing its usability does not yet require a contract or the acceptance of contractual terms, or requesting access rights.

If all interested third parties have access to the API, the term public API is often used. If only selected parties outside the organization are allowed to use the API, the term partner API is used. In addition to these, different parts of the organization can provide APIs for themselves and each other, in which case they are called internal APIs. In many sources, open APIs are defined as public APIs. Some sources also include partner APIs. (Moilanen, Niinioja, Seppänen, Honkanen, API economy 101, 2019). The working group debated whether the term 'open API' can be used for partner APIs.

Increasing openness with open licenses and standards

The openness of the API can be enhanced by openly licensing the data models, documentation and instructions. Also the API should use standard data models where possible.

The use of open licenses and standards is particularly important if the practical expansion of use also requires parties to copy the API over their own information systems and technologies. This is typically related to open source software including an API. Simply copying the API description or data model is not sufficient to ensure that the copied API functions in the same way or remains in the same development cycle as the original. Joint or integrated technical implementation, as well as an open team of developers, may matter more than open licensing on its own.

Open licensing may contribute to the formation and interest of a team of developers. If the entire system's source code is licensed under an open license, the materials associated with the API may be included in this license. If the software or other technology implementing the API has been copied, the terms of use of the data can be completely separated from the terms of use of the API. This means API is run by each consumer on their own network, in their own devices or cloud under their own control. Also the API is interacting with their own resources (data, buildings, algorithms etc.) .

Is the open API always free of charge?

Open data and open source code are often thought to be free of charge. Some definitions also allow a reasonable fee to be collected in order to open the data or source code. However, it is essential to separate the data and the source code from the API itself.

A free or affordable API is certainly more popular and more widely used than an API with a fee. Let's take a look at some use cases.

Free of charge APIs from a business perspective

The use of the API can be free and this is often the case for openly available APIs. In order to make the API usage completely free, we need to go outside of the open source or open data parameters. Consider the costs of the data connection which often depend on the amount and speed of data transmitted via the API. In addition, the total is affected by the purchase or use fees of the technology providing the API, such as a smart lamp or customer information system.

The cost of providing the API can be seen as an investment, marketing cost or, for example, the cost of providing a (customer) service. In one company, previous tailor-made APIs took at least 40 hours per integration, and maintaining and supporting them was laborious and required special expertise.

Although the work was billed to customers, the induction of new employees and supporting users took a lot of time. The maintenance of integrations was not profitable. The prices of implementations would have become too high for customers.

However, integrations were an important reason why customers bought from this company and not from competitors. The APIs enabled the integration work to be entrusted to the customers themselves. the company developed only productized standardized APIs, which were offered to all customers. The company's workload decreased to 2 hours from the previous 40 hours per integration. Complete integrations could be implemented on top of the APIs and offered as fixed-price additional services.

The free APIs offered by companies are often based on the fact that no charge is taken for the use of the API. Yet the use of the resource provided by the API is charged. These resources may include a lamp, a home control system, a CRM system, a paper machine, customer data, or product recommendations processed from data through machine learning. The openness of APIs is therefore influenced by the company's business model. And this is something the API economy may fundamentally change.

For example, a customer can be charged the same fee, whether they use the resource through a user interface or API. In some cases, API consumers are a completely different group from the system's end users. An API may also be offered for partners or for marketing purposes without a requirement for being a customer and related charges. For example, sometimes companies are required by law to provide fully open APIs even to competing companies (e.g. in Finland, the Act on Transport Services or the Open Banking).

Free of charge APIs from the point of view of public administration

APIs provided by public administrations or non-profit organizations may be free of charge or subject to a fee. In the European Union, the role of public authorities prescribed in the PSI directive or in specific legislation require data about the actions of authorities to be public. It is justifiable to provide the related APIs free of charge.

The cost of free of charge APIs are covered by budgetary resources and such APIs are provided in order to achieve a wider economic benefit. However, not all public administration services can be provided free of charge, so as not to distort the market by competing with businesses. In Finland, the State Payment Basis Act regulates the services provided by the state administration, which determines where payments can and must be collected, unless otherwise specified in the legislation. If an Agency wishes to provide an API free of charge, the legislation will also have to be amended or, at the very least, checked as far as it is possible to do so.

A free service provided by a public authority may include a free API. It does not mean that it is justified that the API is opened to everyone, or that its description or data transmitted is openly licensed. The API offered free of charge also requires a statement on how much use can be offered free of charge. Often, as the popularity of the API and the number of applications increase, increasing communication or server capacity also entails more costs. If capacity is not increased, the API becomes practically unusable for its purpose and its use will not be extended. The benefits of openness will not be realized.

In public administrations, APIs are provided with project funding. In particular open data APIs often face this challenge. These APIs often die out at the end of the project funding. Potential private sector users will not dare to commit to use them or plan expansion in the number of users.

Is the data provided or received by the open API always openly licensed?

Not always, but there could be more opportunities than you think. For example, tax information reported by companies to the tax administration through APIs is not, as such, public data. The API might be openly available to all companies providing services to other companies or for their own use. However, some of the data can be published, for example, as open data under the Publicity Act or other legislation relating to tax information.

What are good reasons not to offer a fully open API?

An example of a public service where APIs and data are not fully open, even if they are meant to be widely used, is the TravelDataHub service developed by Business Finland during the year 2020. The API description will be made publicly available under a license which does not allow the API to be copied, at least for commercial purposes. The service aims to guarantee the centralized quality product data of Finnish tourism in selected international travel channels. Data stored in the service is owned by each tourist company. It can be processed by regional tourist offices and can be accessed by marketing channels considered to be of high quality through the API. However, when publishing to some channels, the product data of the travel company becomes at least partially open data because the channel's terms of use require it. This is managed by the tourist company itself. The reason for these channels is, for example, that outdoor routes with their sights are to be offered to various operators who make extensive use of map data for navigation. Such channels may, within the framework of their Terms of Use, publish the data received under an open license through open APIs.

In particular, with regard to platform economy services, which are built with public funds, it should be borne in mind that a vendor lockp can arise in terms of software development and maintenance of the platform, even if the APIs needed to operate the platform are open. It may even be justified to develop an open source solution if you want to ensure that further development and maintenance can be purchased from different suppliers in the future or committed to a wide-open developer community.

However, an open source solution with APIs without joint implementation and a well-run open developer community does not guarantee, for example, cost-effectiveness or speed of development on its own. For example, when different cities start to develop their own differentiated implementations from the same open source solution.

Information considered as users' own data (my data) is also not usually published under an open license, especially if it contains personal data. Other examples include information related to security of supply, national security or corporate secrets.

What is an ecosystem?

In an ecosystem, all actors share a common goal. Otherwise, it's a looser network. In the ecosystem, multiple users are targeted for individual APIs in order to achieve the wider objectives of the ecosystem. The ecosystem may consist of public administrations, businesses, non-profit organizations or citizens/consumers. All these actors can also be present in different roles in the same ecosystem. Operators can provide their common customers with a comprehensive service offering and a customer path where the different resources of the ecosystem are provided in a coherent manner through APIs.

Who's the API consumer?

The API consumers are all those who use (or could) use the API in a technical and operational way and for which the API and the resources it provides are intended to provide added value.

What are the benefits of providing an API?

The benefits for the provider are often the potential of innovation, ease of communicating the resources available and a value promise to the consumers, ease of adding value to consumers through data, services and products. The life cycle of a system or overall solution that uses APIs is often longer, making investments in development more profitable. On the other hand, changes related to user experience or operating models can be implemented more quickly.

From the API provider's point of view, innovations developed by consumers through the API are often a way to obtain and test product development ideas at low cost, without their own significant investment. The provider may also have

Sometimes the provider first has to acquire an information system or technology providing an API or technology as a ready-made software or product, or as software or technology development. The possibilities, costs and access rights of the API may be influenced by the conditions set out in the procurement contract, as well as by licenses and patents related to the technologies used (e.g. programming languages, documentation standards, data models and communication protocols).

The data provided by the API may be owned by the provider or may be data stored by the API consumers. The data Terms and Conditions are therefore to be resolved separately.

What value promises should I offer to API consumers?

The value promise given by the provider to the consumers of the API is often that it is more cost-effective to obtain, for example, functionality, resources (facilities, equipment, know-how, etc.) or data than by making the corresponding solutions itself or providing them with an entire information system, hardware or other resources.

Consumers should be offered an easy way to test (the expression to test is often used, but testing can be seen as broader quality assurance than the so-called pre-procurement testing) the API before deciding to buy, rent or deploy it free of charge. Above all, the consumer of the API should immediately understand where the API can be used. The consumer also often seeks to use the API to generate innovations and possibly commercialize them or make them available to their own users.

What other questions or thoughts arose about the openness of APIs?

Leave a comment or contact us at Osaango - we provide consulting and training in API and platform economies.

Read more about the topic

Discover our latest news & best practises.

Let's stay in touch!

We won't spam you - we'll send you relevant content maximum 1-2 times a month.