Summary

Information is important raw material to modern services. World's most value-producing companies use the information effectively. Also, new business models are based on increasingly efficient utilization of data service processes. Finnish economic growth and productivity can be promoted with effective use of information technology as well as the way of legislation.

Application Programming Interface (API) defines how the software provides information or services to other applications or information systems. While the graphical browser-based user interface, for example suomi.fi, serves the people, APIs provide machine-readable interface for systems and software.

New business models based on interfaces are replacing the old ones. Interfaces based business ecosystems scale effectively and generate API economy. When the APIs are created with public money, business model has to be taken into account. The design should contain an idea of ​​what kind of business models the to be published API supports. If the business model is not recognized, or it is very generic, it is worth to consider once again, if putting money to publishing and maintenance should be done, or whether the money could be spent more usefully elsewhere. On the other hand one can start building the API, and find out if it is called from others in ecosystem. Without experiementation it will be difficult to identify lurking potential of an interface or multiple interfaces.

Currently the public sector seeks to reduce costs all the time. This, coupled with the widespread use of interfaces opens up new opportunities to participate in public service provision. In Finland, the public sector "Only Once" principle can not be applied cost-effectively without the high-quality interfaces.

API Manifesto

Version 1.1 - 26th April 2016

What is API Manifesto?

API Manifesto's story began in September 2015 when Jarkko Moilanen launched a debate on national level API strategy, which was about to find 5-10 theses / measures to promote the API economy in Finland now and in the future. Proposals for theses were crowsourced with open hackpad.

After that we met the Population Register Centre 20th Dec 2015 for more consideration given on how to proceed and in what direction. We chose instead to work on the API manifesto, not yet another strategy. Mika Honkanen was elected as Chief Editor and continued to work in the open for all hackpad.

Working with API manifesto continued in hackpad for while and most of the discussion took place in the API:Suomi Facebook group. In December, the manifesto was transferred to the API:Suomi GitHub and work continued using Github issue lists. On 30th Dec 2015 the first version of the API manifesto was released in Finnish. Work is still continuing and probably continues as long as we have contributions in GitHub. New versions are published in this domain without any premeditated plan. Here are the theses.

1. Serve with digital interface (API)

Begin digital service and information system design with design of the interface (API). All computer programs transfer data through the interfaces. Interfaces based economy (API Economy) has the objective to serve the interface stakeholders electronically as much as possible both inside and outside the organization. Interface is raised at the center of digital operations and it is seen as a way to serve digitally as good as possible.

The interfaces provide added value to digital services and enable the agility of the operation. Make sure that the interface has sufficient service promise (Service-Level Agreement, SLA) and service promise is put on public display. It is important that the interface is operationally reliable and secure. Developers must be provided adequate security for the existence and operation of the interface, so that developers are interested in the interface and more importantly fall in love with it.

In the 1990s, it was important to create a website for each organization. Today, it is important to provide good & open interface, upon which stakeholders can build a variety of user interfaces & user experiences for each terminal. Stakeholders may process and add value to information provided by the interface in a variety of ways. A functional interface makes it easier to react more quickly to changes in technology and the operating environment. Interfaces must be reliable, secure and functional, so that their functionality is guaranteed for years to come. Without the promise of good service interface it is difficult to succeed and stand out from other interfaces, because the developers always opt to choose another one.

2. Prefer transparency

Transparency has proven to produce better quality faster. Transparency help in creating better and more agile service. Open Content License allows for innovation and re-use also for business purposes. Open interface enables easier use of the contents behind it. Include open interface in information system procurement whenever possible. See the definition of an open interface in Finnish: http://avoinrajapinta.fi.

3. Make onboarding as easy as possible

Quality also means good accessibility. The interface it refers also to easy findability and usability. High-quality interface is easy and quick to learn. A good interface has up-to-date documentation, which you can find easily. Good documentation is also rich in the case studies and code examples.

Other ways to improve the developer experience (DX) are including development environments, interface catalogues, automated creation of API keys (for the monitoring of the use), as well as a feedback channel between the interface owner and the developer. Feedback channel is recommended to be something open, for example a message archiving discussion forum. Support the interface utilizing developers in different ways. For example, a telephone service (weekdays 9-16), wikis and email (less than 3 business days to hear the answer) are good ways to support and lure in developers.

New API user will be able to take the best services for use in less than five (5) minutes. The interfaces are reliable (no downtime) and their development / existence has been opened for years to come. One of the biggest problems at the interfaces is still in the fact that testing will take time due to bad or nonexisting documentation. Good documentation provides copy-paste ready example codes (for example in Python & JavaScript), which can then be developed further, rather than reinventing the wheel.

4. Measure, get feedback and iterate

You get what you measure. Measuring the use of the interface is feedback, which you should learn to do constantly as interface provider. Feedback allows iteration, which means a continuous development of the interface with the smallest and the most easily manageable steps. Implement interface versioning if necessary. Interface development is worth striving for in continuous cooperation with its customers.

Measuring the use of the interface is an important part of its design. In practice, you can follow who used the API (with IDs such as IP address, API key, user identification), when was it accessed (date, time) and what kind of information it passed through.

Only then will you know what is needed, and you do not do unnecessary work. Consider also using external test services to help you understand and master user experience.

5. Collaborate with others

Multiple organizations may have similar needs for the API. Find out the possibility for cooperation. For example, 6Aika-cities (Helsinki, Espoo, Vantaa, Tampere, Turku and Oulu) APIs are designed together, rather than each one of them would work independently. Also by working together openly with the developer community you will gain better outcome.

Information behind the interface is rarely perfect. The fastest way to improve its quality is feedback provided by the community. Communities can also help by creating code examples, which in turn will facilitate onboarding of the interface. Vibrant and diverse ecosystems are build around excellent interfaces.

6. Implement consistently

The interfaces are consistent regardless who implements them or with what technology is used. They use the same design patterns, but they also leave room for maneuvering and adjusting. The all-encompassing standardization is impossible. Extensive multi-hundred-page requirement specifications are usually already outdated when completed. You should try to ensure that the interfaces operate in a consistent way. Content of the open interfaces of the public sector should be provided under one license. Also, the interface Terms of Use should be consistent. Use international (de facto) standards whenever possible. Standards help facilitate harmonization and exploitation.

7. Build for purpose

A good interface is build to meet a particular need. API must be publicly designed and with a published life cycle. The interface is designed, implemented, used and finally decommissioned. The interface is part of today's user interface design, which also takes into account applications alongside humans. Build a narrowly defined, practical and easy-to-implement interfaces. One good measure of the quality of the interface is how quickly and easily it can be taken into use.

In the documentation, publish API's designed lifespan (for future upgrades, versions, etc.) and update the plan regularly.