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

The digital transformation journey is so fundamental that it requires changing our DNA.

~John de KeijzerHead of Enterprise Architecture & Technical Strategy

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

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!

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.

SendSMSPOST /v1/messaging/sms/outbound/tel%3A%2B<YOUR_NO>/requests

Header: “client_id:U6bUkRzU192AsGCfWt5QFABUtOqWmX4B”Header: “Content-Type:application/json; charset=utf-8” \{ “outboundSMSMessageRequest”: { “address”:[“tel:<RECIPIENT_NO>”], “senderAddress”:”tel:<YOUR_NO>”, “outboundSMSTextMessage”: { “message”:”Hi there!” }, “clientCorrelator”:”Some_id_to_search_the_logs”, “receiptRequest”: { “notifyURL”: “”, “callbackData”:”” }, “senderName”: “ACME Inc.)” }}

We’ve been surprised about how much SMS is needed by developers. We rarely see an app without SMS usage! Right now we offer SMS limited to usage inside Switzerland, but international SMS will come soon.

~There’s life in the old dog, yet.

PaymentThe 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.

POST /payment/tel%3A%2B<THE_CUSTOMERS_NO>/transactions/amountAccept: application/jsonContent-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.

Payment

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

The API program teamHow 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.

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.

The API program team

IdentityA 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!

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.

Identity

Age checkAre 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.

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.

Age check

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 ...

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.

The customer info APIIn the end it’s all about customers ...

GET /customerProfile/v1/queries/customerProfileAccept: application/json{ "customerProfile": { "forename":"John", "surname":"Doe", "houseNameOrNumber":"100", "street":"Main street", "city":"Atlantis", "zipCode":"abc123", "contactTelephoneNumber":"tel:+41791234567", "language":"en" }}

We will give access to basic informa-tion, addresses, contracts, notifications, 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.

The customer info API

Intelligent searchThere 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

Cloud 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.

The Swisscom Cloud eats (consumes) APIs ...

{ "services": [{ "id": "service-guid-here", "name": "mysql", "description": "A MySQL-compatible relational database", "bindable": true, "plans": [{ "id": "plan1-guid-here", "name": "small", "description": "A small shared database with 100mb storage quota and 10... },{ "id": "plan2-guid-here", "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" } }]}

Our digital transformation journey consists of three overlapping waves: the All IP, the API and the Cloud wave.

Cloud APIs

Vidia 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”.

Our video conferencing solution.

/rooms

/rooms/{roomId}

POST

GET

Not every backend service is relevant to be exposed on the API layer. We pick out the pearls.

... and there are so many.

Vidia

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.

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.

Let’s talk about GREENFIELD

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

The API-kitchen – Evangelism 2.0... because Hackathons are really not enough!

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.

... 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.

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.

Should we follow best practices?

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.

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-

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.

ImprintLinks: 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