1. 1
The Swisscom API journey #2
... it still requires changing our digital DNA

2. 2
Content
What happened so far ... 4
Imagine ... 5
Wheretop-downcrashesintobottom-up 7
It'saboutspeakingacommonlanguage 9
We had no clue, about how long the initial exposure phase would last ... 13
Wehavetorethinkourpretzel 15
Projectcentrismvs.APIcentrism 17
Theimportanceofanorthbound-map 19
Nosuccesswithout libraries 22
API-Management reloaded 23
(Why)shouldweavoidaggregation? 31
If we could go back in time ... 32
Things that are really hard to stand ... 33
The first API meeting in London ... 34
ElevenrulestokillanAPIprogrameffectively 35
About Swisscom 37
Imprint 39

3. 3
Changing our DNA doesn’t mean making things
‘a little bit better’ – it’s a fundamental change in
our nature rebuilding our way of working,
– from ground up!
IT-Coach & API-Evangelist
~ Kay Lummitsch

4. 4
What happened so far …
Seriously – The Swisscom API journey #1 raised
more questions than it answered. How could such
a small book be so successful?
1100 printed copies, over 2500 views on slideshare,
countless downloads and so many positive com-
ments from all over the world.
Awesome!That exceeded our highest expectations!
Edition #1 led to various discussions, and showed
that many enterprises are facing the same prob-
lems, even if the Powerpoint presentations are
sometimes telling a different story.
Answering the initial question – We made great
progress. Currently we’ve exposed more than thirty
APIs consumed by internal departments and com-
pletely changed our team set-up.
2015 is meant to be ‘The year of proof’.
~ The Swisscom API program team – March ‘15
We’re supposed to show that our elephant is finally
able to dance.
I’ve often been encouraged to work on a second
edition – so, today we’re happy to present you The
Swisscom API journey #2 – A deeper view
Thanks to all of you.

5. 5
Imagine ...
After having coffee I go to our huge, loft like
office, say Hi to the laughing guys in the entrance.
“Hey everybody! Welcome to our API kitchen”.
Wooden floor, big windows, beanbags and white-
boards. Architects sit amongst designers and de-
velopers discussing the implementation of an API
extension. Others work on the next API. Right next
to them, in the break-out area, developers are talk-
ing with business guys and app developers, show-
ing how their ‘problem’can be solved with existing
APIs.
They’re smiling!
In the middle of the room is a big open spaced kitch-
en. Kay is preparing omelettes for some developers,
teaching them about best practices.
Nearby is the Start Up Corner where Start Ups work
(for free). Currently two developers are with them,
gathering information about new trends in the
community.
Three plasma displays show the traffic on our gate-
way. “Wow – that’s a lot of traffic”. Another curve
shows revenue growth. We’re making money with
our APIs!! It’s already lunchtime and Kay serves
omelettes whilst standing around a huge wooden
table, talking about our next big vision for APIs …
* The so called Miracle question invented by Steve de Shazer – American psychotherapist
The API fairy comes into your room tonight, taps your head with
her magic wand – and all your problems are solved the next
morning. How would your day look like? *

6. 6
Pete Parker – CIO for Acme Inc., drops in. Formerly
in charge of enterprise services at Worldwide Insur-
ance Corp., he now leads a $10 billion big data initi-
ative. Acme Inc. is one of our long-time happy cus-
tomers, and is about to revolutionise our daily lives.
They use our partner APIs heavily, and are about to
reach their request limits again! We're discussing
pricing options to give them more requests. Great
to see how much we are helping them and that our
APIs are covering their needs – our customers are
making good business with our APIs.
That’s how a day
could look but the re-
ality is still different.
~ Imagine ~

7. 7
Where top-down crashes
into bottom-up
Edition #1 named it ‘Conflicts welcome’ –
here we want to go deeper into it.
Whenever business meets technology, tensions will
arise.
If we asked the business colleague afterwards, he
would answer something like this:
“Good Lord Help – This tech guy has absolutely no
idea what I’m talking about!”
And surprisingly the tech guy would answer:
“Lord have mercy Dude – This business guy has ab-
solutely no idea what I’m talking about!”
Seems funny but it isn’t – it’s our daily experience!
Unfortunately they are right – both of them –
100%.
Starting the API program, we hit the same prob-
lem over and over with no idea why we crashed so
hard. Back then, the team was composed of one
business representative and me – The API-Evange-
list – engaged in the development unit setting up
the API-Factory.
Whenever this business guy came, telling me how
things should be done, we ended up arguing. In the
end you could hear the sentences which mentioned
above.
Each of us saw arrogance and incompetence in his
opposite.
... crash-test-dummies at work

8. 8
... If we only had
a common language ...
Leveraging an API program means dealing with
this tension. We live in the hot-zone. That’s the
place where the friction starts between business
and technology. APIs provide a great opportunity
to bridge this divide.
What are we doing about this problem?
We have passionate discussions in meetings, always
keeping in mind that roles are speaking here – not
arrogant or even incompetent people. This helps
enormously.
Is it possible to overcome the divide between busi-
ness and technology in general?
In terms of APIs see – next chapter
~ Where top-down crashes into bottom-up ~

9. 9
It’s about speaking a
common language
... do you speak "API-ese"?
We’ll take the picture on the right to illustrate
two of our current problems.
The general naming problem
> APIs are named to fit the initial business request
(following our standard process), or the develop-
ment project. In this situation nobody knows what
is in the box.The names don’t reflect or describe the
APIs in any form. And they are tremendously sticky.
> APIs are named after internal development ver-
sions (that’s a hard one too!)
Internal backend system names & version pairs
are swooshing to the northbound interface. These
names have an extreme tendency to be seen at the
exposure layer ~ if we are not taking care of that.
> Finally the real API names (as they should be), are
not relevant to the affected stakeholders, and do
not play a role in this whole game.

10. 10
This little picture came into existence during an API core team meeting.
B = Business | T= Technology
~ It’s about speaking a common language ~
APIs
B T

11. 11
The communication/information problem
If APIs and we – the team that runs them
– are aiming to be accepted as the proxy between
Business and Technology, we have to be able to:
> Answer all relevant questions from the business/
consumers
> Hide anything that’s not absolutely relevant to
the business/consumers
> Protect the development unit from any business
interference
Being involved early is our current approach. We
started that involvement with an open attitude,
through consultancy and orchestration. Now we
step between the lines delivering appropriate infor-
mation and consultancy to the business (the North)
and useful information to development (the South).
In the near future you will hear us saying things like:
To the business/consumers:
“Project/Request X is going to make use of ‘API A’
and an advancement of ‘API B’. These will be ready
in X weeks from now. We are thinking about how
to provide you an ‘API-C’ to make it much easier to
adapt with your next project.“
To the API-Factory:
“We’ll need the customer-core-info_3.22.19 to de-
liver the enhancement to the Customer-Info API in
X weeks.”
As long this is not done, business will continue to
address development directly, and vice versa, as it
has always been.
~ It’s about speaking a common language ~

12. 12
The API program team has to become the commu-
nication proxy between North and South – exactly
like our APIs!
If we start by solving the communication problem,
the naming problem will solve itself.
Once this is done ... we’ve installed a common lan-
guage.
APIs!
~ It’s about speaking a common language ~

13. 13
We had no clue, about how long the
initial exposure phase would last …
... or how to keep the business units in-game
Our enthusiasm for APIs led to expectations
on the business side that the time to reap the ben-
efits had begun. Sadly it took way more time than
expected to expose neat and reusable APIs.
It's rare to hear voices talking about the problems
that arise during the exposure phase, and there are
plenty. The experts we met at conferences mainly
agreed on that. They are all facing more or less the
same problems. Seemingly, there is no formula for
success out there.
A well-known attitude inside big enterprises is to
differentiate external customers from customers
that belong to the own company. “This is just for
internal usage” – is an often-heard sentence.
We are putting in lots of effort to treat business
units as important customers instead of treating
them as ‘fellows in misery’.That seems obvious, but
it has to be done actively.
A business unit is not interested in exposing APIs – a
business unit is primarily interested in bringing their
new product to market – making use of whatever
technology that is able to make this happen.
We do not want them to be part of our struggle
anymore.
Our job is to consult them from the very beginning,
and keep them away from backend related discus-
sions, problems and complexities.

14. 14
~ We had no idea, about how long the initial exposure phase would last … ~
“I don’t care, if it takes you six months to
create a new API – I simply don’t care!”
~ Business representative during the TAD-Summit (Istanbul 2014)
Funnily, that’s exactly what an API is supposed to
do. That’s how we raise the trust in APIs.
see – it's about speaking a common language, p. 8

15. 15
We have to rethink our pretzel
We have to segregate data-delivery from data-management
An enterprise our size has prescribed stand-
ard-software-development-process to develop soft-
ware with a clear segregation of responsibilities.
Unfortunately this stays the same when it comes
to API-Development, -Exposure, -Management.
One consequence is that the development depart-
ment is responsible for:
> High enterprise-quality development of APIs
> Security & governance of these APIs
They have to make APIs enterprise-robust and save.
But not only in the technical context. They are still in
charge if it comes to the question: “Which amount
of data will be shown to whom?”

16. 16
~ We had to rethink our pretzel ~
In our case this led to APIs that suited exactly to a
given original business request. And this is frankly
“The same thing we did before – We just added an
API in front of it!” – And even worse, we produced
various APIs that are doing nearly the same thing.
Once we realized what we were doing there, we
stopped that immediately.
We decided to segregate data-delivery from da-
ta-management.
The data-delivery is responsible for bringing the
data to the service-exposure-layer and the da-
ta-management will have to decide, which amount
of data should be shown to whom – and it’s getting
even better – the data-management-team will be
enabled to make multiple behavioural changes to
the API without touching the originally proxy at all.
That was the missing part!
... until now …
“Experience is the name everyone gives to their
mistakes.”
~ Oscar Wilde

17. 17
Project centrism vs. API centrism
... on preventing ugliness
Our former approach to develop/expose/
manage APIs led to project driven APIs and an infla-
tionary growing amount of proxies, all of which are
doing nearly the same. The final APIs often serve a
single customer and are designed for very specific
use cases. Reusability of these APIs tend towards
zero. Each new project gets their own private API.
That’s what we call project-centric APIs.
Project-centrism is neither efficient nor does it scale.
We need a way to switch to API centrism. We want to
develop and expose APIs which are usable for many
use cases. We want reusable APIs.
As an enterprise we know how to develop software
in projects for many years. Processes are in place.
People are used to working with longtime product
life cycles, defined requirements and relatively slow
change processes. Establishing an API program -
even starting to expose APIs – doesn’t change an-
ything at first. For the developers the API program
just adds more API ‘projects’. We’re still vulnerable
to complexify things even more.
You read about the naming problem pointing to
the babylonian mess that can arise during API de-
velopment. You read about the problems finding
a new way to leverage cross-layer communication
and about the changes we made in our information
strategy. All this helps to become API centric. But
one – absolute crucial part is still missing.
A map of your future northbound interfaces.
see – next chapter

18. 18
~ Project centrism vs. API centrism ~
“You won't be able to please everyone – Aim to
displease everyone equally.”
~ Joshua Bloch: How to Design a Good API & Why it Matters,
Keynote at OOPSLA'05, San Diego, California, October 2005.

19. 19
The importance of a northbound-map
Leading the process is impossible without a northbound vision
How to change from reactive mode, – pledg-
ing to expose as many APIs as possible, generating
sudden usage and revenues – to leading the pro-
cess, and being the captain of our huge API-Ship?
Let’s take this analogy:
We have a good knowledge of the harbour we’re
departing from ...
“We know what we want to get rid of …”
We have great expectations for trading opportuni-
ties at the target harbour ...
“We’ll be part of the API business and generate great
new revenues.”
We also have a vague map of the seas between ...
“We’ve got a strategy!”
Get into active-mode!

20. 20
~ The importance of a nortbound-map ~
© Andrew Mackinnon
Hopefully you have a book like this
in your hand to help you ride the
storms en route to API-Town …

21. 21
It’s where we translate backend assets into an
easy-to-understand API-Portfolio. In the morning
we’re discussing urgent problems – in the afternoon
we are shaping the future.
The approach reduces workload and uncertainty
on every layer. Things do not have to be solved over
and over again, and we are able to address the main
problems mentioned before.
Let’s keep on shaping!
But, because we’re in a hurry, we are dropping goods
over the railings on the pier at the target harbour!
That’s the next challenge to deal with.
We need a precise understanding of the rules and
conditions at the target harbour and a plan to op-
timise the unloading of goods to meet customer
expectations.
So, we’re creating a map! Shaping our northbound
map is extremely important to us.
The API-Design-Circle is a weekly interdisciplinary
meeting composed of enterprise-architect, solu-
tion designer, enterprise-service-bus specialist, API
product manager, developer and – of course – the
API-Evangelist. We also invite API-Experts and ex-
ternal community specialists to keep our thinking
outside-the-box.The Circle shapes both our current
API landscape and the course we steer.
~ The importance of a nortbound-map ~

22. 22
No success without libraries?
We often hear that “Our API program cannot
be successful if it doesn’t provide libraries’’. Indeed,
there is cool stuff out there that reads WSDL/RAML/
YAML/Whatever descriptor files and automatical-
ly generates libraries for most of the commonly
known languages.
Nevertheless, at the beginning we had to focus on
our first-level-APIs.
Now – as our map is taking more and more shape
we’re planning to provide libraries for our API con-
sumers.

23. 23
API-Management reloaded
“20% success is not enough!”
On the face of it, dealing with APIs seems to
be technical – technical interfaces, technical services,
and developers who think technically. Summarized –
this is tech-stuff. Our experience is that dealing with
APIs is 20% technical and 80% cultural. All the tech-
nical problems and details are solvable – the cultural
changes are much more difficult.
It follows that we’ll be just 20% successful if we focus
only on technical aspects.
So, keeping in mind that we aim to change our digital
DNA, we must do more.
You read about the separation of data-delivery and
data-management earlier in this book – that’s a cul-
tural move!

24. 24 This approach will enable us to deploy a new API...
... not in 6 months ... not in 6 weeks ...
(hold tight!) ... in many cases half a day!
~ API-Management reloaded ~

25. 25
Why (summarized):
Our former approach led to project-driven
APIs and a growing number of proxies doing nearly
the same thing.
In the future, we want to configure a fully-fledged
proxy using some kind of consumer profile – this
means the API will initially return the maximum *
amount of data which the consumer profile will
filter according to what the consumer is allowed
to receive.
Example: The API will return the full customer pro-
file with all details: addresses, contracts, subscrip-
tions, etc. but the end consumer will only receive
the first-name and the last-name.
This will unclutter our API offering enormously.
Thinking ahead, this will be the only way to keep
our APIs maintainable and manageable.
It will also reduce the workload for the API-Develop-
ment team because one proxy will be able to handle
multiple requirements.
* logic that prevents unnecessary backend requests is planned
~ API-Management reloaded ~

26. 26
What do we need?
Naked proxies: Future proxies should be deployed
naked, without any authentication/authorization.
Auth attributes should be switched on- and off-
using the consumer-profiles advice.
And again: Different authorization/authentication
scenarios will make use of the same proxy.
Full-fledged proxies (data-delivery at it’s finest):
Future proxies should deliver the maximum *, rea-
sonable amount of data in the context of the re-
quest.
Consumer profiles & filter engine: We want to be
able to apply consumer-profiles to API-Keys.
A filter policy should make use of these consum-
er-profiles and filter the returned data by the pro-
files advice.
The consumer profile is also able to make behav-
ioural changes to the API.
Consent engine: The consumer-profile should also
control the requests for consent.
Reporting capabilities: We want to be able to an-
swer questions regarding consumer access to data
at any time.
Governance: Each consumer-profile has to be ‘bless-
ed’ by the governance board.
Future thinking: Extension of the Profile-Syntax
to enable/disable querying at resource level with
query parameters as well as choosing between full
response, or links to subtypes and address trans-
lations.
* logic that prevents unnecessary backend requests is planned
~ API-Management reloaded ~

27. 27
{
“profileName“ : “CUSTOMER_BASIC“,
“productName“ : “happy-customer“,
“proxyName“ : “customer-info“,
“auth“ : “OAUTH2|NONE|BASIC“,
“consentRequest“ : “CUSTOMER_BASIC“,
“visibleFields“ : [
“customer.firstName“,
“customer.familyName“,
“customer.dateOfBirth“,
“customer.addresses.MAIN|*|plz“,
“customer.subscribtions.*“,
“customer.locations.LINK_ONLY“
]
}
Let’s have a look to a pseudo-profile:
~ API-Management reloaded ~

28. 28 … this little piece of Json code is able to revolutionize
our time-to-market!
~ API-Management reloaded ~

29. 29
~ API-Management reloaded ~
... at a glance
{
"firstName": "Ursula",
"lastName": "Schweizer",
"addresses": [
{
"streetAddress": "Hauptstrasse",
"houseNumber": "15"
}
]
}
{
"firstName": "Ursula",
"lastName": "Schweizer",
"language": "DE",
"gender": "female",
"birthDate": "1966-04-24",
"nationality": "CH",
"id": "1234567890",
"email": "u.schweizer@swisscom.com",
"addresses": [
{
"streetAddress": "Hauptstrasse",
"houseNumber": "15",
"city": "Zurich",
"postalCode": "8012",
"country": "CH",
"type": "main"
},
{
"streetAddress": "Nebenstrasse",
"houseNumber": "16",
"city": "Zurich",
"postalCode": "8013",
"country": "CH",
"type": "correspondence"
}
]
}
Filter
API-Gateway
Filtered response
according to profile
Full response returned by the API

30. 30
~ API-Management reloaded ~
This is an easy-to-use enterprise approach that will
improve and accelerate our work tremendously.
It will also enable us to separate data-delivery from
data-management – the cultural part.
Now the missing 80% is coming into our field
of vision.

31. 31
(Why) should we avoid aggregation?
... about losing control
It’s not unusual to hear during conferenc-
es that enterprises have a tendency to dislike ag-
gregation. We find ourselves in a similar situation
whenever aggregation is a topic of discussion.
The main concern is that aggregation decreases
performance and leads to unpredictable behaviours
in case errors occur. We risk to lose control and to
slip into random error-handling mechanisms.
So we have to aggregate with costs nearly ZERO
and deliver aggregated APIs that are predictable.
We’ll accept the challenge!
Surely, it does take time and energy to get there,
but for an enterprise, aggregation is not a job to
rush.
Once we know how to do it an enterprise-robust
and safe way, we are going to aggregate like crazy!

32. 32
… we would:
If we could go back in time …
> Setup the API-Factory, the API-Program team & the API-Design team
> Create a list of all relevant backend assets
> Enable Monetization/Analytics
> Introduce the common language - APIs
> Implement our northbound map step-by-step
> Design the northbound map ~ mapped to the list of assets
> Enable the platform to support ‘API-Management – reloaded’
> Setup the developer portal & provide API-Sketching
at the portal (Yaml/Raml) including speed mocking
> Implement a core API making use of all topics of this list
> Make our business units happy

33. 33
> It's hard to prove that APIs are reducing friction as long you're producing more friction and costs
than before.
> It's absolutely frustrating to organize hackathons without a minimum set of cool APIs.
> It’s hard if you can’t show a mock or test version of your APIs until they are finally exposed.
> It's hard to be forced to please everybody and to be accused for pleasing everybody at the same time.
Anton Rodriguez Yuste | Telecom Solutions Architect
> It's hard to fight proxy wars between business and technology in your own team. Consider
yourself lucky if you are friends enough to stand these. Stephan Karpischek | IT-Strategy consultant
> It's hard to make successful SOA APIs that have specific programming language dependencies.
Eugene Ciurana | Founder at Cosmify, Inc.
> It’s hard to propose APIs as a solution as long as no one sees a problem. Frank Buettner | Technology strategist
Things that are really hard to stand …
If you do not resonate with the following list – you made it!

34. 34
On March 22nd
we met in London for our first
EMEA-API meetup. Participants from the UK, from
Norway, the Netherlands, Germany and of course
Switzerland invested time and effort to talk about
their experiences in leveraging an API program.This
has been extremely insightful.
The discussions went far beyond the slide-show
level and we realized once again, that enterprises
have well known, common problems. And to share
them is a pretty good way to solve them. We are go-
ing to meet quarterly at different places in Europe.
The first API meeting in London …
… it’s about sharing experiences
Please ask to join our upcoming meetings.

35. 35
Eleven rules to kill an API
program effectively
ASK "WHY DO WE NEED API's"
AS OFTEN AS POSSIBLE
INCREASE COMPLEXITY
WHEREVER POSSIBLE
ASK EVERYBODY
– ALWAYS!
TURN ALL YOUR ENERGY INWARD
TRY TO BE PERFECT,
RIGHT FROM THE BEGINNING

36. 36
AVOID READING THIS BOOK!
(NEW & RATHER FUNNY)
DO EVERYTHING THEORETICALLY
FOCUS
ON PROBLEMS
BE EXTREMELY CAREFUL!
CREATE PROCESSES AROUND YOUR PROCESSES
OPEN AS MANY SECONDARY
STAGES AS POSSIBLE
~ Eleven rules to kill an API program effectively ~

37. 37
About Swisscom
Swisscom is Switzerland’s leading telecom provider with its headquar-
ters in Worblaufen, close to the capital city, Berne. With over 20,000 employees
it generated turnover of CHF 2.82 billion in the first quarter of 2014. Swisscom
is one of the most sustainable companies in Switzerland and Europe.
What we stand for
As a trustworthy companion in the digital world, we want to win peo-
ple’s hearts, make things simple and shape the future so our customers feel
safe and at ease.
Products and services
Swisscom offers mobile communications, fixed networks, Internet and
digital TV to corporate and residential customers. We are also one of Switzer-
land’s largest providers of IT services. We build and maintain the mobile and
fixed-network infrastructure, transmit broadcast signals and own shares in
media companies.

38. 38
Our employees
Swisscom employs more than 17,000 staff at locations throughout
Switzerland, around 1,000 of whom are apprentices. Around one in three
have direct daily contact with customers, either in sales or customer service
departments. Swisscom offers its staff excellent working conditions within
the framework of a collective labour agreement.
Who we work for
The Swiss telecommunications market has an estimated annual turno-
ver of around CHF 17 billion. Our market share varies between one- and three-
fifths, depending on the field. Swisscom has decided to focus on residential
customers, small and medium-sized enterprises and large corporations.
~ About Swisscom ~

39. 39
Imprint
Author: Kay Lummitsch
Passionate change maker | IT-Coach | Catalyst
API-Evangelist, Zurich – Switzerland
mail: kay.lummitsch@swisscom.com
mobile: +41 79 154 47 81
linkedIn: Kay Lummitsch
Co-Author: Stephan Karpischek
IT strategy consulting , Zurich – Switzerland
mail: kpi@kpi.at
mobile: +41 79 790 79 57
linkedIn: Stephan Karpischek
Design: Maude von Giese
Graphic Designer, Zurich – Switzerland
mail: maude.vongiese@gmail.com
mobile: +41 79 269 94 50
linkedIn: Maude von Giese

40. 40
Webversions: Edition #2
bit.ly/1DnIETv
Edition #1
bit.ly/1basqBk
Links: swisscom.ch
developer.swisscom.com
@swisscom_api
Special thanks to: Matt Chalmers (Apigee),
Eva Endress (Self employed),
Chris Novak (Apigee),
Christin Schmidt (Business-Coach)
Sarah Murphy (Swissom) for helping us with the text.
And of course the Swisscom API program team.
2nd
edition, March 2015
~ Imprint ~

41. 41