This document outlines 10 lessons learned from Europeana's experience developing APIs and transitioning to being an API platform. Some key lessons include: APIs need more than just technology to succeed and require activities to promote adoption; showing concrete applications is important for gaining organizational buy-in for APIs; copyright issues can significantly hinder API adoption if not clearly addressed; and marketing and outreach are necessary for developers to learn about and use a new API. The document advocates for careful documentation of data, user experience design for developer portals, and accepting that failures will occur in the process of learning.

1. Top 10 Lessons Learned
In our ongoing shift of Europeana as a portal to Europeana as a
platform
David Haskiya, Product Development Manager

2. Europeana is an organisation that is
passionate about cultural innovation.
Sitting at the intersection of culture and
technology, our aim is to open up Europe's
creative and cultural wealth to as wide an
audience as possible.
Because Cultural Innovation:
- Advances society both economically and socially
- Unites Europe through a shared cultural heritage
- Celebrates the wealth of cultures across Europe
- Enables personal growth and development

3. My Top 10 Lessons Learned

4. Lesson #1: APIs are means and not
ends

5. It's not just about the technology

It's what you as an organisation and business can
accomplish with an API that you can't without

An API needs to be carefully packaged into a number of
other activities in order to fully succeed

Since I'm not a technologist I won't be sharing any lessons
on technical API-design, but on the lessons I've drawn
from the mistakes and successes we've made at
Europeana over the last 3-4 years as APIs have gone from
a loose idea towards a core service

6. Lesson #2: Show, don't tell...

7. ...is key to getting buy-in

In my organisation very few colleagues and even fewer
partners knew what an API was in 2010

A lot of effort was needed to get full organisational buy-in

Getting buy-in from our funders was difficult. You need to
be able to explain in it in terms of business that they
understand
•
Having a couple of applications helps a lot

The buzz of the hackathons we arranged in 2011 were key
in getting internal and external buy-in

You need to be able to measure success. Quantitatively,
qualitatively, convincingly.
•
Yes, non-profit organisation or government agency, that
means you too!

8. Lesson #3: Copyright is the killer of
confidence

9. Eliminate doubt and confusion!

Usually the most obscure part of your Terms of Use and
thus a main cause of non-adoption

Can stop you cold even if you've done all the technology
aspects right
•
Our API was semi-open for too long! It caused bad-will and
doubt among developers

And is usually much more difficult and slower to change
than what your technology
•
It took us almost 2 years to convince all of our data
providing partners to CC0 their metadata and adopt a
structured licensing framework for media served

Adopt standard licences as much as possible and support
the public domain

10. Lesson #4: When the guerilla war is
won, governing begins

11. From guerilla to governor

In many organisations APIs are developed guerilla style at
first by one or two firebrands, skunkworks style.

When you get organisational buy-in APIs become truly part
of your business with all that it entails

The guerilla phase tends to be more fun. Your explore new
concepts and technologies and you are the consensus

When the API becomes part of the line business the
meetings set in, the overhead, the consensus building...

Now you need to govern. It's not for everyone. Either move
on or soldier on. And if you move on, don't kibbitz your
successor.

12. Lesson #5: Document your data

13. Data usability is essential

Content is as key to API-design as it is to web design or
app development
• Document it with as much care as you do for your API, if
not more
•
We learned this lesson late! Now we're investing in featuring
the best of our data

Investing in data quality always pays off in the long-run,
whereas code has a short half-life
•
Try to solve fundamental data issues at source, rather than
hide them by code
•
When aggregating data from multiple sources align to one
model and normalize strictly!

14. Lesson #6: Build it and they will NOT
come

15. Your API is here! How do you tell the
world?

Unless you're extraordinarily lucky you need to to market
and communicate your API for it to get traction with
developers and customers

The Zen paradox of API-marketing:
•
An API is like any other product and must be marketed like
any other product in order to be succesful
•
An API is not like other products and cannot be succesfully
marketed like any other products

This is probably a fake paradox. But it can be difficult for
an organisation get the perspective and balance right.
•
We're still working on it

16. Lesson #7: Developers are users too!

17. They're not THAT special

Just because they're power-users of the web doesn't mean
you shouldn't invest in API-documentation or developer
portal UX

The methods and processes of UX-design can be
succesfully adapted and applied to APIs and developer
portals
•
Our soon to be released developer portal is our first we're
we've researched and designed as we would a consumer
site
•
We're still not as good at documentation as I would want us
to be

18. Lesson #8: Hackathons ≠ Developer
Outreach

19. The gospel of API-evangelism

Consider what hackathons are good for and not
•
In my sector (libraries, archives, museums) I often feel they're
held because it's what everyone does

Fold your hackathons into along-term outreach/community
programme
•
Community outreach is labour intensive one marketeer doing it
with 10% of of his or her attention won't cut it

Be inclusive when you organise them and don't profiteer
on the efforts of the participating developers
•
There's an increasing body of hackathon best practices

20. Lesson #9: Some lessons you need to
learn yourself. Again. And again.

21. You will #FAIL

If you're new to developing APIs and the business of APIs
you will do your research carefully and make mistakes
anyway
•
I remember listing many pitfalls to my management when we
started with our API development. Then I fell in them.
•
I think the business related pitfalls are deeper and easier to fall
into but that could be because I'm not a developer.
•
Quick iterations makes for shallow pits discovered early

If you're experienced in developing APIs and running a
API-centric business you will make mistakes anyway
•
You can hopefully climb out the pit faster the second time

The government sector can have a very hard time
accepting that you can fail forward

22. Lesson #10: I actually don't have one,
but I'm willing to listen

23. That was it! Questions? Comments?
Grab me in a break or get in touch.
Email: david.haskiya@kb.nl
Twitter: @david.haskiya