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.
7 API economy boosting principles in Finland - now and in the future
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.
Functional interfaces are the precondition for the creation and scaling of digital ecosystems.
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.
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.
Use developer portal to gather material to gain accessibility (and make it pretty).
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.
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.
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.
6. Implement consistently
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.