The Swisscom API journey document outlines Swisscom's efforts to transform into a digital company by exposing its services through APIs. It details the creation of an API program team to oversee API development. Swisscom established an internal Apigee platform called GREENFIELD to allow agile API development and testing. Through initiatives like the API-Kitchen events, Swisscom aims to educate internal developers and change its culture to embrace APIs. The document shares lessons learned and APIs Swisscom has developed, like ones for SMS, payments, customer info, and video conferencing.

1. The Swisscom API journey
... it requires changing our DNA

2. The digital transformation journey
is so fundamental that it requires
changing our DNA.
~John de Keijzer
Head of Enterprise Architecture & Technical Strategy

3. Why we wrote
this booklet …
We created this booklet in order to share
our experiences in becoming a state of the art
API provider. The Swisscom API program started
in September ‘13 in cooperation with Apigee. We
went through all the typical difficulties that come
along with such a big change process.
We are still learning and would like to start a dis-cussion
to find new ways to cooperate beyond the
past “thinking in silos” in order to move forward
to a connected world.
The Swisscom API team
Zurich, August ‘14

4. Let’s talk about APIs
We identified more than 120 relevant APIs we want to
expose by the end of 2015. The API program prioritizes the
development roadmap together with the various business
units. We want to show you just a few of these APIs and share
our insights. All your feedback is welcome!

5. SendSMS
The telco’s must-have
Of course, we have a SendSMS API. We have imple-mented
one GSMA compatible as well as a simplified version.
Each developer gets 100 SMS per month for free. After that,
further usage will be charged using Apigee’s monetization
capabilities. The variant “SMS token validation” is currently
heavily used by Swiss developers.

6. SendSMS
POST /v1/messaging/sms/outbound/tel%3A%2B<YOUR_NO>/requests
Header: “client_id:U6bUkRzU192AsGCfWt5QFABUtOqWmX4B”
Header: “Content-Type:application/json; charset=utf-8”
{
“outboundSMSMessageRequest”: {
We’ve been surprised about how much
SMS is needed by developers. We rarely
see “address”:[““senderAddress”:”an app tel:<RECIPIENT_without NO>”],
tel:<YOUR_NO>”,
SMS usage! Right
now “outboundSMSTextMessage”: “message”:”},
we {
Hi there!”
offer SMS limited to usage
inside “clientCorrelator”:”Some_id_to_search_the_logs”,
“receiptRequest”: Switzerland, {
but international
“notifyURL”: “”,
SMS will come soon.
“callbackData”:””
},
“senderName”: “ACME Inc.)”
}
}
~There’s life in the old dog, yet.

7. Payment
The carrier billing API
After many years of experience with payment solutions
for partners, we offered an one-to-one adaption of our pay-ment
solution as an API. We are now going one step further
and offering a GSMA compliant payment solution. This offer
will enable developers to create cross-operator applications.

8. Payment
POST /payment/tel%3A%2B<THE_CUSTOMERS_NO>/transactions/amount
Accept: application/json
Content-Type: application/x-www-form-urlencoded
endUserId= tel%3A%2B<THE_CUSTOMERS_NO>&
transactionOperationStatus=charged&
description= Swiss%20Chocolate&
currency=CHF&
amount=3.99&
referenceCode=REF-12345&
clientCorrelator=54321&
onBehalfOf=Swisscom%20Chocolates&
purchaseCategoryCode=Food&
channel=WEB&
taxAmount=0
The payment API forced us to deal with
the OAuth process. Every transaction
requires the explicit consent of the end
user. This authentication / authoriza-tion
approach seemed to be easy, but
implementing it into our infrastructure
showed up to be a more complex task.

9. GSMA – OneAPI
OneAPI is a global GSMA initiative to
provide APIs that enable applications to ex-ploit
mobile network capabilities such as
messaging, authentication, payments and
location-finding with a cross-operator reach.
~source: gsma.com
OAuth2
OAuth is a protocol that enables app end users to authorize apps
to act on their behalf. Apps do so by obtaining access tokens from API
providers. The API provider authenticates the app end user's creden-tials,
ensures that the user has authorized the app, and then issues
an access token to the app. When the app consumes a protected API,
Apigee Edge checks the access token to ensure that it is valid and that
it has not expired. As an API provider, you need to expose endpoints
that enable apps to get access tokens.
~source: apigee.com

10. The API program team
How to concentrate knowledge ...
It was absolutely neccessary to set up a team of experts
to leverage our API approach. This team is composed of special-ists
from every involved layer. We have a core team that glues
them all together and members that are temporarily in charge.
This leads to extremely short communication ways and shared
knowledge spanning over management, strategy, business,
legal, API developers, enterprise architects, backend developers
and the operation guys.

11. The API program team
Conflicts welcome!
“Hello conflict. Good to have you here
so early to find the best solution.” The
API program involves every layer of
our corporation and all of them want
to be convinced.

12. Identity
A really huge task ...
Companies like us own many customer / partner enter-prise
systems that are nearly incompatible, causing data isola-tion
and redundancy. Our new digital strategy approach is to
consolidate all customer / partner records into one meta-iden-tity
system, which is a huge task. Swisscom will become a fully
grown identity provider for six million customers very soon!

13. Identity
When we started the API program,
everybody thought about expos-ing
cool longtail APIs. However, af-ter
further thinking, we decided to
quickly add business value by focus-ing
on uncluttering our back-ends
and expose our assets through our
internal developers.

14. Age check
Are you old enough?
Ensure that your customer is older than sixteen or
eighteen years old (or twenty one for United States custom-ers)
to sell them specific products. Allow developers to create
apps for alcoholic beverage purchases. Web shops can also
be enabled to check the end users age.

15. Age check
GET /agecheck16?telNo=<TEL_NO>
GET /agecheck18?telNo=<TEL_NO>
This age check method leads to discus-sions
such as “What if my child uses a
phone with my contract?” We need to
solve this problem.

16. Credit check
... limit reached?
The credit check API enables developers
to check the balance of a prepaid account.
Seemingly trivial – but absolutely
timesaving for internal developers ...

17. The customer info API
In the end it’s all about customers ...
This API allows access to all relevant information of a
specific customer. The amount of information revealed by
this API is managed by the access level of a given API con-sumer.
We are able to give every partner exactly the amount
of information he subscribed for. For example, if I am an in-ternal
accounting application I may be able to access more
information than a Swisscom partner application can.

18. The customer info API
GET /customerProfile/v1/queries/customerProfile
Accept: application/json
{
"customerProfile": {
We will give access to basic informa-tion,
addresses, contracts, notifications,
"forename":"John",
"surname":"Doe",
"houseNameOrNumber":"100",
"street":"Main street",
"city":"Atlantis",
"zipCode":"abc123",
"contactTelephoneNumber":"tel:+41791234567",
"language":"en"
}
}
subscriptions, discount codes, billings
and E-Vouchers. The customer will be
redirected following the OAuth process
to authenticate and grant access to the
relevant information.

19. Intelligent search
There you are!
Search customers, products and relevant data more intel-ligently
in our systems. This search is supposed to be wildcard
enabled and allows fragments in the search terms.
/search

20. Cloud APIs
The Swisscom Cloud eats (consumes) APIs ...
Our cloud is hungry, so we need to expose APIs to make
the Cloud possible and provide a method to access all other APIs
directly from VMs in an stunningly easy way. The Cloud API is
like the “foot in the door” to our corporate back-ends. Since the
cloud is external to Swisscom’s enterprise, it is secured by the
API “security standard” and blessed by our governance process.

21. Cloud APIs
{
"services": [{
"id": "service-guid-here",
"name": "mysql",
Our "description": "bindable": digital "A MySQL-transformation compatible relational database",
true,
journey
"plans": [{
consists "id": "plan1-guid-here",
"name": "small",
of three overlapping waves:
the "description": All IP, the "A small shared database with 100mb storage quota },{
"id": "plan2-guid-here",
API and the Cloud wave.
and 10...
"name": "large",
"description": "A large dedicated database with 10GB storage quota, 512MB...
"free": false
}],
"dashboard_client": {
"id": "client-id-1",
"secret": "secret-1",
"redirect_uri": "https://dashboard.service.com"
}
}]
}

22. Vidia
Our video conferencing solution.
Vidia allows you to exchange ideas with customers, em-ployees
and partners, hold presentations and maintain relation-ships
in a virtual room. Unlike a traditional meeting room, your
Vidia meeting room is a virtual one. All participants can be in
different places, and join the discussion with their own computer,
tablet or smartphone. We will provide several APIs supporting
developers to hook on Vidias “foundations”.

23. POST
/rooms
GET
/rooms/{roomId}
Not every backend service is relevant
to be exposed on the API layer.
We pick out the pearls.
... and there are so many.
Vidia

24. The API-Factory
... creates heavy duty corporate APIs
We started developing APIs with a small team following our standard
development process, which is built to guarantee heavy duty corporate services.
It soon became clear that the underlying slow enterprise development cycles
are not agile enough for the expectations of our customers and stakeholders.
The challenge was to be be extremely agile and enterprise heavy duty. We
need both!
To accommodate both, we decided to keep the standard process and also create
a highly effective development unit for the heavy duty process. The API factory
was born. This team is able to do a great job when the requirements are already
clear. The challenge is not to overload the API factory with trial-and-error and
fail-fast stuff. This is done somewhere else, long before the API factory comes
in charge.

25. Let’s talk about GREENFIELD
How to make an elephant dance?
After the API-Factory was in charge, we established an internal only
Apigee platform named GREENFIELD and invited devolpers to expose their
backend services on their own without worrying about security, performance,
best practices, etc. The slogan is: “Just make it happen!” On GREENFIELD de-velopers
are able to play around and create showcases, test stuff and throw it
away if it’s not reasonable. This platform is made to fail fast and it is absolutely
agile. Once everybody agrees that an API is profound and mature enough, the
package will be delivered to the API-Factory.
The business was able to see the examples and showcases right from the be-ginning,
instead of waiting months for everything to be properly blessed and
approved for production use by the organziation. Afterwards, the factory guys
are able to shape the APIs into Swisscom standards and apply all the required
features no one on GREENFIELD had to worry about. Throughout the whole
GREENFIELD process the developers are guided and coached by factory devel-opers
and the program team to prevent divergence. The initial step to convert
developers to API developers was to invite them to our API-kitchen events.

26. The API-kitchen – Evangelism 2.0
... because Hackathons are really not enough!
Changing our corporations DNA needs a ground up, inside out, grass-roots
movement to make the digital transformation happen. We initiated a
set of recurring events called the API-Kitchen where we educate our internal
developers on how our new API ecosystem works while dining on excellent
food. The food is cooked by a well known Swiss TV-Chef. The first all day
event is called the APItizer. This day provides a high level overview on the API
strategy and development. Day two is a developer event. The main course.
We teach them how to expose their backends on the Apigee platform. At day
three (the dessert) we also invite frontend developers to create showcases
consuming the newborn APIs.
Showtime at the end. This ap-proach
lets 1000 APIs bloom in
a very short time and fosters the
internal acceptance of APIs.

27. Should we follow best practices?
... trying to always be right
We had a lot of discussions regarding best practices /
design policies with sometimes divergent outcomes. On top
of that, our first APIs did not follow any of these rules because
our processes where not ready at the time. We see ourselves
still in a learning process and the mindset change on all levels
[Management / Business / API-Factory / Backend developers
/ Operations] takes a while. Instruments like the API-Factory
(see page 28), the API program team (see page 12) and the
API-Kitchen (see page 30) are helping us enormously along
this path.

28. Should we follow best practices?
If you ask a corporation: “Why do you
do it in such a complex way?”, the
answer is often: “This is historically
grown”. A powerful API program will
help us to get out of the slow corner.

29. Governance
Opening a corporation through a digital strategy doesn’t mean
inevitably opening it only to the outside world. An API program opens
the corporation to itself, giving a large organization flexibility to trans-form
itself.
A corporate culture reacts to an “opening” with an impulsive knee-jerk-ing
reaction to “close”. And that is exactly what an API program has
to deal with.
A reasonable governance process has to be established to convince
all stakeholders that their data is safe in this new open environment.
Every public and partner API needs
clearance by the management board.

30. About Swisscom
Swisscom is Switzerland’s leading telecom provider with
its headquarters 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 people’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 Switzerland’s largest providers of IT ser-

31. vices. We build and maintain the mobile and fixed-network
infrastructure, transmit broadcast signals and own shares in
media companies.
Our employees
Swisscom employs more than 17,000 staff at locations
throughout Switzerland, around 1,000 of whom are apprentic-es.
Around one in three have direct daily contact with custom-ers,
either in sales or customer service departments. Swisscom
offers its staff excellent working conditions within the frame-work
of a collective labour agreement.
Who we work for
The Swiss telecommunications market has an estimated
annual turnover 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.

32. Imprint
Links: http://swisscom.ch
http://developer.swisscom.com
@swisscom_api
Contact: Kay Lummitsch
mail: kay.lummitsch@swisscom.com
mobile: +41 79 154 47 81
twitter: @lummitsch
Skype: lommex
Author: Kay Lummitsch (IT-Coach, API-Evangelist – Switzerland)
Design: Maude von Giese (Graphic Designer, Geneva Area – Switzerland)
linkedIn: Maude von Giese
Special thanks to Chris Novak (Apigee) for helping us with the text.
1st edition (web), September 2014