How do we put

“API First” first?

Gravitee.io, 2021. All rights reserved.

 PAGE 2

API First

How do we put “API First” first?

‘API First’ is an approach that can help enterprises and organisations to adapt to the new
rules of the digital market. But what does the term mean, and how is the approach
implemented in order to take advantage of the benefits of APIs?

We define API-First as:

API First is a whole-of-organisation approach that leverages APIs to support strategy,
architecture, and teams to work collaboratively and in unison towards agreed goals.

APIs are:
A contract that defines who should be able to access what (and how much) of each of the data and
services being made available,
An efficiency multiplier that reduces the risk of IT components, digital services and datasets
needing to be created within each interface or system (for example, by duplicating an IT team’s
work when building both iPhone and Android apps, or by creating duplicate databases in each
business unit when designing data flows across multiple departments)
An ecosystem builder that allows key partners, third parties, and consumers themselves, to co-
create new products and services built off your core business systems,
A digital enabler that speeds up the delivery of new features, products, services and workflows,
and
A data infrastructure element that lets you better collect timely data on usage, performance, and
demand, to provide business insights. (APIs as data infrastructure also allow businesses to plug
into artificial intelligence tools and privacy-enhancing technologies to support an organisation’s
maturity as it moves beyond being a digital organisation, to being a data-enabled organisation.)

Taking an API First approach means taking a whole-of-organisational perspective that allows APIs to
be successfully leveraged to enable all of the above benefits.

Gravitee.io, 2021. All rights reserved.

 PAGE 3

How do we put “API First” first?

API first is the business and technical

mindset to produce and publish the API
before building the different UI products
or the clients consuming it. This enables
faster internal re-use, allows new features
to be added based on feedback and
demand, and encourages value discovery
within emerging ecosystems.

Mehdi Medjaoui, co-author of Continuous

API Management, Founder of the apidays
conference series, and founder of two API-
first startups

I usually discuss API-First with business as making sure the

business is API-enabled: I work with their business goals and ask how
will APIs help them achieve that? At a tech level, there is a strong
interest in API-driven architecture, but engineers need to understand
how APIs support the business. Talking about the developer
experience of the APIs they consume helps them see the importance
of an API-First approach to building an ecosystem. And at the team
level, every team that is actually building software needs a team
member with an understanding of APIs as business-enablers:
whether that be product, marketing, or more technical teams.

Marjukka Niinioja, Founding partner at Osaango, Founder of the

APIOpsCycles Method, and author of API Economy 101

Gravitee.io, 2021. All rights reserved.

 PAGE 4

API First

The greatest challenge when

becoming a digital organisation
After an organisation has gone through a digital transformation phase and updated its systems
and operations to digital approaches, there is still a period where the organisation tries to replicate
what it was doing in an analogue environment into this new digital way of working. With that
mindset, a business (from strategy, to architecture, to the way teams are structured) would be
inclined to see APIs as simply an integration technology that connects two or more systems
together.

But in a digital organisation, that mindset is an obstacle, as it limits thinking around how APIs could
be leveraged to build products faster, to onboard partners and customers more seamlessly, and to
encourage all teams to be more productive and reduce duplication.

Organisational API First API First API First

Obstacle
level Mindset in Practice Driven Outcomes

Strategy We need to think like Will APIs help us Revenue from new

a platform and grow achieve our business digital business models

an ecosystem goals? Wider reach

Increased customer

acquisition
“APIs are a
technical issue”
Architecture
We need to build Are we using APIs as Less duplication

products rapidly and the ‘composable unit’ Greater efficiency

securely that enables us to Faster product

build flexibly and development

securely at all times? Less breaking changes

Secure operations

Automated processes
“APIs are an
integration
Teams technology” We need to make API Does every team Happier teams
expertise a part of understand APIs and Higher productivity
our organisational where to get more Multidisciplinary
knowledge information? thinking
Quality delivery
Collaborative, data-
driven creativity

Gravitee.io, 2021. All rights reserved.

 PAGE 5

API First

Understanding the
real value of APIs
Technical teams have long known that APIs can be used to:
enable partner and customer onboarding,
avoid duplication in each system interface,
prevent database duplication,
strengthen security and reduce vulnerability, and
automate workflows.

But decisions to support technical teams to build and make APIs available for these purposes are
business and strategy decisions.

Let’s look again at the ways APIs can be used, and what business decisions need to be made to
enable their value to be leveraged:

enable partner and customer onboarding -> This requires a business strategy that implements
a platform business model and fosters an ecosystem approach
avoid duplication and recreation in each system interface -> This requires a business strategy
that calculates costs and prioritises creating efficiencies
prevent database duplication -> This requires work across multiple (often siloed) business
units or departments and the creation of cross-organisational assets such as a data registry
that makes a dataset available to each department (which departments may fight against as
they fear it means their budget will be reduced if they access a shared resource)
strengthen security and reduce vulnerability -> This requires a business strategy that sets user
access permission controls for each role within the organisation and for each role in the
ecosystem
automate workflows -> again, this often requires multiple business units working together to
share resources and create common systems and approaches.

To leverage the full potential of APIs requires a new business mindset - an API-First approach
- that actively seeks ways to build digital business models, foster an ecosystem, empower IT
architecture, and support cross-team productivity with APIs.

That’s why we believe API First is an approach that should be implemented across three levels:
API First in Strategy
API First in Architecture
API First in Teams.

Gravitee.io, 2021. All rights reserved.

 PAGE 6

API First Strategy

API First Strategy This digital approach also gives you greater
Why does a business, government department, insight into each of your customer’s individual
network or another type of organisation need to needs and their interaction history, and enables
you to create a much more granular,
understand APIs? What is the benefit of thinking
personalised experience for each customer
about strategy from an API First approach?
without the expensive overheads of building
individual bespoke solutions.
Today’s enterprises and governments are
currently completing a wholesale digitalisation Digital operations also allow you to move
shift. This goes much deeper than having a towards a platform model. Platform business
modern website and online checkout. It is about models allow you to enable stakeholders
transforming your internal operations and (suppliers, partners, and third parties) to make
processes into digital workflows and systems: use of your core assets: the unique data,
managing digital datasets and services for services, and processes that to date have
everything from HR and payrolls to stock allowed you to interact and provide products to
your customers and users.
inventory to fleet management. All are catalogued
digitally. Operational systems that hire, roster and
Platform business models can spur your
pay staff, restock and order items, and arrange
success in the digital economy. Customer
vehicle maintenance and leasing, are now all done demands are too widespread (and constantly
through integrated, digital systems that can also evolving) for you to meet everyone’s needs.
generate real-time insights, automatically set Digital has also meant that customers want to
alerts, and even order repairs themselves. access your organisation’s services wherever
they are: whether that be device-driven, like
from a tablet, phone or watch, or interface-
driven, for example, within another business’
website or from within location mapping
software.

Even though new digital systems may have

been put in place, your team of business
leaders may continue to struggle with
understanding the true potential that these
new digital systems allow. Your organisation
can better brainstorm the new opportunities of
your digital systems if you start with an API-
First mindset.

Gravitee.io, 2021. All rights reserved.

 PAGE 7

API First Strategy

At the strategy level, empowering an API First mindset means starting with the question:
Will APIs help us achieve our business goals?

Use case example: University of Helsinki

Student management at the University of Helsinki requires student data to be shared across
multiple software systems. The university could have taken an API as an integration technology
approach and simply made sure that student data was integrated across the multiple software
systems in use. Instead, the University of Helsinki thought, “with APIs in place, how can we now
provide our 30K+ new students each year with a seamless university journey?”

“Now we are seeing business leaders talk about APIs,” said Tapio Piironen, IT Specialist and Team
Manager at University of Helsinki. “Business leaders are interested from a product development
point of view and from a resource point of view. With product development, they are asking: has this
been built with APIs? What other products could we build with those APIs? From a resource point
of view, we have a lot of external partners we work with, so business leaders want to see how we
can work with these external partners securely via APIs, without duplicating our internal efforts.”

Implementing an API first approach at the business strategy level seeks to overcome the obstacle
of seeing APIs as purely a technical concern. Instead, APIs are seen as a key business enabler in
creating an ecosystem. Business leaders seek to first identify how APIs could help achieve business
goals. This leads to creative thinking around how to create an ecosystem of partners, and to work
with third parties to extend reach and acquire new customers.

Organisational API First API First API First

Obstacle
level Mindset in Practice Driven Outcomes

Strategy “APIs are a We need to think like Will APIs help us Revenue from new
technical issue” a platform and grow achieve our business digital business models
an ecosystem goals? Wider reach
“APIs are an Increased customer
integration acquisition
technology”

Gravitee.io, 2021. All rights reserved.

 PAGE 8

API First Strategy

How to move forward with an API First mindset Can we share any existing APIs with external,
at the strategic level trusted partners to help build a more diverse
Look at your business goals for the next quarter, range of products for our customers?
half-year or year. In business strategy teams, ask: Can we use our existing APIs to gain greater
How can our existing APIs help us deliver on insights into customer demands, operational
our goals? How do our APIs help us reach costs and inefficiencies, or gaps in our market
new customers, strengthen existing offerings?
customer relationships, onboard partners, What new APIs could we create for business
make use of our data for insights, and purposes?
automate repetitive processes? Can we use tools like Gravitee’s API Designer to
Can we use our existing APIs with our SaaS bring business and technical teams together to
and software tools to create automated design APIs that help us achieve our priority
workflows for repetitive tasks? What business goals?
efficiency gains would we expect to see? Can
we prototype automations and workflows Throughout this ebook, we will visit three use cases:
using internal APIs and no code tools? In banking/finance
Can we use our APIs to build new product In health
features, onboard new customers, or offer In government
new services faster?

For each sector, we will ask: How can API First be applied at this level?
At a business strategy level...

Sector Banking and finance Health Government

Strategy need To make sure that new open To make better use of our data We need to reduce operational costs
banking services are built in to accelerate new health involved with digital services delivery as
accordance with new banking solutions by working with we have multiple departments buying
regulations external researchers and third expensive datasets and each building
party health tech partners their own digital services components
like form-filling and payments

Key strategy How can APIs help us meet How can APIs help us work How can APIs help us reduce
question regulatory requirements? with external partners? operational costs as we move to
provide more digital services to
citizens?

Strategy solution We can design all finance APIs We can expose our data We can create a single source of truth
using a common template that securely via API to authorised data registry so we only have one
conforms with regulatory external parties to allow version of each dataset, and all
requirements. This helps us multiple partners to build and departments can use an API to connect
meet regulatory requirements test solutions at the same time to the database we maintain. We can
and helps us ensure that our as our internal teams. offer a single payments API and a single
partners also match our input form API so that each department
regulatory compliance. can use these components when
building their digital services.

Gravitee.io, 2021. All rights reserved.

 PAGE 9

API First Architecture

How do we leverage APIs to build future-proofed, Use case example: Tide

secure, ease to evolve, flexible IT architectures Digital small business bank, Tide, saw its
while maintaining pace with the need to release a membership double every year prior to COVID,
steady stream of new products and features? and this accelerated even faster as SMEs
turned to 100% digital solutions during the
pandemic. As an SME-banking specialist, Tide
As part of your digital transformation agenda, your
also needs to ensure that accounts can
IT leadership team has probably broken down your
integrate with account keeping software, and
organisation’s monolith and rebuilt your internal to enable apps on phones, tablets, and in ERP
legacy infrastructures into a collection of systems. Building from an API first approach,
microservices connected via APIs. Tide can keep up with the pace of client
onboarding, while extending its offering into
But just as we have seen with your business new digital form factors, and integrate with an
strategy decision-makers, it is equally as easy for ever-widening array of business software.
your architecture and software teams to fall into
the trap of perceiving APIs as “just” an integration An API first approach instead looks at what
functionalities need to be exposed in the
technology.
product to be built. The engineering team looks
to see if these API functionalities are already
When a budget has been allocated to build a new
available in your internal API catalogue. If not,
product, for example, engineering teams often they work with the relevant business team to
jump at the chance to create a new solution. They map out what capabilities are needed in the
focus first on what the end-user app might look API, using a design first approach, so that the
like, and what functionality it has, and they start API can be used not just in the immediate app
building the software. When they do consider being built, but for other similar business needs
APIs, it is in terms of using APIs as a mechanism that might be one or two steps into the future.
that links the app interface to a database, or to
consume external APIs, like location mapping in Granular access and permission controls are
also defined for each API capability to ensure
the app.
that the API is built securely. An API
specification file is created to ensure that as
For architecture teams, taking an API-first
the API is built and tested in the lifecycle
approach means starting by designing APIs and development process, and API design lifecycle
using them to build new products, services, tools automatically check progress against the
features, and automated processes. An API First intent and security parameters of the initial API
mindset starts with the question: design so that scope creep is avoided.
Are we using APIs as the ‘composable unit’ that
enables us to build flexibly and securely at all Overall, this leads to faster and repeatable
times? product development and allows continuous
integration/continuous development that tests
the API and ensures that it aligns with the
intended purpose and security constraints.

Gravitee.io, 2021. All rights reserved.

 PAGE 10

API First Architecture

Organisational API First API First API First

Obstacle
level Mindset in Practice Driven Outcomes

Architecture “Let’s start We need to build Are we using APIs as Less duplication
building!” products rapidly and the ‘composable unit’ Greater efficiency
securely that enables us to Faster product
“APIs are an build flexibly and development
integration securely at all times? Less breaking changes
technology” Secure operations
Automated processes

How to move forward with an API First mindset at the architectural level
Before commencing any new product, service, feature or workflow project, ask:
What existing internal APIs could help us build this solution?
What new internal APIs are needed to expose functionality for this solution?
What is the full list of functionalities and capabilities needed for this solution?
Which will be the business and product team responsible for maintaining this API product
once it is built? Can we involve them in defining the API specification and defining the
capabilities that are needed? Do we understand the future business use cases that could be
built using any new APIs we build for this specific solution?
Have we identified risks and security vulnerabilities that may emerge from exposing these
capabilities via API?
Have we defined an identity access permission policy to address these risks?
Are we taking an API design first approach to the APIs we do build?

At an architecture level...

Sector Banking and finance Health Government

Architectural We need to build a new iPhone We want to be alerted in our We need to create a form so that
need app for our customers systems when patients are citizens can enter their information
prescribed medications that
are dangerous when mixed
together

Key architectural What functionalities will need What datasets can be exposed What are the common elements that all
question to be available through the by API to support a workflow to departments will need to have displayed
app? identify risks? in a form?

Architectural Build APIs for each Build APIs for data registries Create a form-filling API that can be
solution functionality so that they can that describe medication safety used by any government department to
be used to build the iPhone risks collect citizen information
app and future apps like an
iPad app or an Android app

Gravitee.io, 2021. All rights reserved.

 PAGE 11

API First in Teams

How do we encourage an API First mindset and organised can only ever reflect the wider
across the whole organisation? organisational structure of the business.

In practice, encouraging an API First mindset So for an API First mindset to influence strategy
amongst strategy and architecture will mean that and architecture decisions, API First will need to be
every team within the organisation will need an embedded into the organisational structure, or it
understanding of APIs and where to go internally will be continually overlooked.
to find out more. An API First approach suggests
that the value of APIs is understood as part of In an API-First organisation, someone on every
the organisational knowledge that is shared by team would have some level of expertise around
all. APIs, even if it was just an overview of what
business value APIs can provide, where they can go
For digital businesses, there is a software for more help and how to access the internal API
development rule known as Conway’s Law. This catalogue. A cross-organisational centre of
axiom says that the way software is developed excellence, or centre of enablement team, that
helps everyone make use of API resources and best
practices can also help.

The creators of the Team Topologies model have identified four types of teams that exist in
digital organisations:

Team typology Team function

Stream-aligned A team aligned to a flow of work from a segment of the business domain, for example,
team an engineering or product management team working within a line of business

Enabling team A team that helps the stream-aligned team overcome obstacles and detects missing
capabilities, for example, a centre of excellence team

Complicated A team where significant math/calculation/technical expertise is needed, for example,

subsystem team a data science team

Platform team A grouping of other team types that provides an internal product to accelerate delivery
by Stream-aligned teams, for example, an IT departmental team responsible for an
internal API catalogue

Gravitee.io, 2021. All rights reserved.

 PAGE 12

API First in Teams

In an API-First approach, each type of these teams would include someone who would have some
level of API expertise:

Team typology Team function

Stream-aligned Understanding of any of their own APIs they produced

team Knowledge of how to enlist support from the enabling team
Knowledge of how to find the API resources from the Platform team
Creative skills in understanding how to leverage APIs for business strategy

Enabling team API best practices

API tools to support best practices

Complicated Knowledge of how to enable access to technical products and skills via API, for
subsystem team example, the data science team would include someone who knew how to feed
existing data into machine learning projects via API, or from machine learning
projects into the rest of the organisation’s work

Platform team API best practices

Management of whole-of-organisation API supports, such as an internal catalogue
or a style guide

To support members within each team to take an A catalogue of approved third-party APIs that
API-First approach, a range of tools may be can be used
needed: A selection of no-code tools that anyone could
An API governance framework that outlines use to build prototypes using internal and
how priorities are set around what APIs external APIs
should be built, how security and risk should Kanban or other tools to track internal
be assessed and managed, what standards developer-identified bugs and feature lists
should be used, how new APIs are reviewed, Open source participation and pull
etc request/commit process policies
Templates to help teams develop internal Core metrics to ensure oversight of API
APIs, such as the API Team template from performance, usage and fitness for purpose.
Team Typologies
An API style guide and agreed set of Not everything needs to be built at once, but over
standards to be used when developing APIs time, as the organisation moves towards the API
An approved API lifecycle development tools First mindset, these supports will help tam
directory members in each type of team to ensure APIs are
An internal API catalogue considered at the start of any new project.
Documentation and use case examples for
each internal API

Gravitee.io, 2021. All rights reserved.

 PAGE 13

API First in Teams

For teams, taking an API-first approach means moment they are working on defining an
having at least one person on each team who is organisational-wide style guide to support the
able to propose when APIs could be used to consistent design of APIs. In addition, Piironen says
support organisational work. An API First that business leaders are aware of the advantages
mindset starts with the question: of APIs: “Business leaders are asking: has this been
Does every team understand APIs and where built with APIs? What other products could we build
to get more information? with those APIs? From a resource point of view,
business leaders want to see how we can work with
Use case example: University of Helsinki external partners securely via APIs, without
The University of Helsinki’s IT Systems duplicating our internal efforts.”
Department has organised its API-related teams
into several groupings that match the Team Encouraging teams to develop an API First
Topologies model. Tapio Piironen, IT Specialist approach helps bridge the gap between business
and Team Manager at University of Helsinki, says and technical teams: strategy and architecture can
that each programming teams (stream-aligned work together by developing a common
teams) are each encouraged to make their APIs understanding of the organisational benefits of
available on the internal catalogue so that other using APIs. Teams can be more productive and
teams can make use of them. Teams that more efficient by reusing existing internal APIs,
address the needs for specific use calculations building to standards and using style guides, and
(complicated subsystem teams) are making can better implement best practices to create
those functionalities available as microservices quality results. Overall, this makes team members
APIs that can be used by others. The Platform happier, as they are less frustrated by
team, meanwhile works on building supports and miscommunications and repetitive tasks, and can
best practices to support other teams: at the see the value of their work more clearly.

Organisational API First API First API First

Obstacle
level Mindset in Practice Driven Outcomes

Teams “Our team We need to make API Does every team Happier teams
doesn’t think expertise a part of understand APIs and Higher productivity
with an API-First our organisational where to get more Multidisciplinary
approach” knowledge information? thinking

Quality delivery
Collaborative, data-
driven creativity

Gravitee.io, 2021. All rights reserved.

 PAGE 14

API First in Teams

How to move forward with an API First mindset at the team level

Review your organisational structure and ask: Which of the supports are in place to make it
Is there someone on each team who easier for teams to make use of APIs:
understands the value of APIs? Style guide
Is there someone on each team who knows Design templates
how to ask for help with APIs? LIfecycle tooling
Is there an organisational-wide team Internal developer catalogue
delegated to be the centre of Use cases and documentation for each
excellence/centre of enablement or another internal API
type of knowledge support to help teams Governance processes like how to define
take an API First approach? identity and access permission policies?

At a team level...

Sector Banking and finance Health Government

Team need Product teams want to expose Data governance teams need Policy teams need to know that
a credit scoring service to to know that health data can be government can achieve more by
industry partners shared more efficiently with making APIs available to create core
partners digital services and so that external
providers can create targeted products
for specific populations

Key team How can business services be Does a team member know When a policy describes the need for
question exposed in a way that that APIs can help enable cross-sector collaboration, does the
enhances ecosystem interoperability if datasets are team invest in pilot studies using new
partnership opportunities? built to API technical technology to exchange information or
standards? do they seek to use APIs to scale
faster?

Team solution The technical writing member A member of the data A member of the policy team
of the product team is able to governance team is involved in understands that APIs can be used to
create new developer ensuring that data models are create secure methods of exchanging
resource content that helps built to standards that can data so funding to implement pilots
external partners make use of support technical testing new security exchange
a credit scoring API interoperability technologies does not need to be
included

Gravitee.io, 2021. All rights reserved.

 PAGE 15

About Gravitee.io

Effortless control of your

API ecosystem
Our API Platform is the richest Open source solution available. We help organizations unify
APIs into an easy-to-use and secure space.

The Gravitee.io Platform has everything your business needs to integrate your APIs all in one
place, allowing you to manage and secure your APIs effortlessly. Built using an intuitive, configure
rather than code approach.

Start with the Open Source Edition of API Manager or Access Manager and effortlessly expand to
the Enterprise Edition to benefit from API Designer, Alert Engine and Cockpit.

To discover more about the Gravitee.io full lifecycle API Management Platform,
visit www.gravitee.io or book a demo today.

SCHEDULE A DEMO

Gravitee.io, 2021. All rights reserved.