These are the slides presented to DeveloperWeek Europe 2021 about how API Definitions go beyond just our OAS definitions even for internal use cases

1. © 2021 – Phil Wilkins – mp3monster.org
Phil Wilkins
Tech Evangelist & Ace Director
Phil.Wilkins@capgemini.com
uk.linkedin.com/in/philWilkins
@PhilConsultant /
@MP3Monster
Oracle-integration.cloud /
APIPlatform.cloud /
Blog.mp3monster.org
API Design – More than just a
Payload Definition

2. © 2021 – Phil Wilkins – mp3monster.org
The About Me …
Me in 6:
• Family man, Blogger & Author
• Technical Architect, Tech Evangelist
• Work for Capgemini UK as part of a multi
award winning team
• Work with primarily open source + Oracle
middleware
• Recognized by Oracle as an Ace Director –
domain knowledge & community contribution
• Know more – mp3monster.org
https://blog.mp3monster.org/
publication-contributions/
https://bit.ly/FluentdBook
https://bit.ly/ImplementingAPI
https://oracle-integration.cloud

3. © 2021 – Phil Wilkins – mp3monster.org
Capgemini is One of the World's Largest Consulting,
Technology, and Outsourcing Firms & a global “full
service” business transformation provider
Group Workforce: 200,000+ Globally
Asia Pacific
Latin America
Canada
United States
Mexico
Brazil
Argentina
Europe
Morocco
Australia
People’s Republic of China
India
Chile
Guatemala
Russia
Singapore
Hong Kong
North
America
UK & Ireland
Nordics
Benelux
“It is the quality of our people, and their
capacity to deliver fitting solutions, with you
and for you, that drive real business results.”
Across 40+ countries, 100 nationalities
5Businesses
Revenue
12,8
Billion EUR (2017)
Central Europe
Morocco
Net Profit
€1,18B
 Targeting Value
 Mitigating Risk
 Optimising
Capabilities
 Aligning the
Organisation
Elements to
successful
collaboration
Application Services
Infrastructure
Services
Business Process
Outsourcing
Consulting
(Capgemini Consulting)
Local Professional
4

4. © 2021 – Phil Wilkins – mp3monster.org
APIs, more than a
Payload?

5. © 2021 – Phil Wilkins – mp3monster.org
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
The parts of OAS we focus on when developing an API

6. © 2021 – Phil Wilkins – mp3monster.org
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
The parts of OAS we focus on when developing an API

7. © 2021 – Phil Wilkins – mp3monster.org
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
Terms of Service – go look over there …

8. © 2021 – Phil Wilkins – mp3monster.org
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
Security controls – not obvious …

9. © 2021 – Phil Wilkins – mp3monster.org
API Wall for External APIs
Authentication
&
Authorization
SDK
/
Code
Generator
Test
Framework

10. © 2021 – Phil Wilkins – mp3monster.org
But my API is not for
external use!

11. © 2021 – Phil Wilkins – mp3monster.org
… Yes but will you be supporting your API
for the rest of your career or it’s lifecycle?
What about the impact of an
API Gateway on your API?

12. © 2021 – Phil Wilkins – mp3monster.org
Internal API Gateways
We should be considering internal gateways to …
• Enforce rate limiting to avoid possible runway processes swamping you with API calls
• Creating points of abstraction
• GWs can mask changes in deployment for consumers
• Enforce loose coupling – some APIs are intended operational purposes NOT for others to
build new applications against
• Gateway as a focus of security management
• Provide easier points for measuring utilization (investment value)
All these points are not easily defined in an API spec

13. © 2021 – Phil Wilkins – mp3monster.org
Supporting Adoption and Change
Every time someone wants to use your API internally, do you want to be receiving over
Slack, Skype, Teams, email random questions about …
• Where do I test my use of your API?
• My call keeps failing – why?
• How do I get credentials to use your API?
• Why can’t I …
All these points are not easily answered in an Open API spec
• We talk about self service in our everyday lives, many of us even prefer it
• Many API Design Tools offer mock endpoints – tell people where it is
• Provide examples – so people can see what will work and why
• Point to the internal process or service for securing access
• You can deliver an SDK to make it easier to use your API faster than anyone else when it
comes to coding – you know the API best

14. © 2021 – Phil Wilkins – mp3monster.org
API Wall for External APIs
Authentication
&
Authorization
SDK
/
Code
Generator
Test
Framework

15. © 2021 – Phil Wilkins – mp3monster.org
API Wall for Internal APIs
Legalese
Authentication
&
Authorization
SDK
Test
Framework

16. © 2021 – Phil Wilkins – mp3monster.org
Still with me ?
Solving the problem …
Biproduct / benefits

17. © 2021 – Phil Wilkins – mp3monster.org
What to do ?
1. Create yourself a checklist like our “wall”, decide what “bricks can help” in a situation
2. Use a design tool that provides mock end points & share the links
3. Provide additional docs ..
1. Answer the sort of questions / points discussed, could be simple as Markdown in your
repository
2. Incorporate the doc reference into the API Spec
3. More accessible the supporting content – the better
4. Try to avoid burying answers in big docs.
4. Think about what you’d want when trying to use an API, and what if it doesn’t go right
5. If you get asked for the same thing more than a couple of times – address it, own it rather
than problems own you (better than the continued interruptions, debates about
accountability)

18. © 2021 – Phil Wilkins – mp3monster.org
Feedback
Design
Build Package
& Deploy
Try Continuous
Test
Feedback
Run
Analyse
Feedback
Build Package
& Deploy
Try Continuous
Test
API Provider
API Consumer
API 1st
Explination to API first:
https://apievangelist.com/2020/03/09/what-is-api-first/

19. © 2021 – Phil Wilkins – mp3monster.org
Being the next Elon Musk
Not all of us, have the benefit of working on APIs for those poster
children of the API Economy, But …
APIs done right can…
• See opportunities to expand on current services – offer the
same service in different ways – Walgreens photo printing,
PSD2 Banking (new user experiences)
• People can see the ‘art of the possible’ with your API and realize
new solutions etc
From this you could say
over 60% of organizations
see good API Design as
key to their future
Cloud
Elements
State
of
API
Integration
Report
2018
Good API Docs is key to
this
Good API Design is key
to this

20. © 2021 – Phil Wilkins – mp3monster.org
Better handle & communication on how your API will
evolve and version

21. © 2021 – Phil Wilkins – mp3monster.org
Not be the cause of a security issue (or better be the
person who helped prevent one)
A1:2019- Broken
Object Level
Authorization
A2:2017- Broken
Authentication
A3:2019-
Excessive Data
Exposure
A4:2019 - Lack
of Resources &
Rate Limiting
A5:2019-
Broken
Function Level
Authorization
A6:2019- Mass
Assignment
A7:2019 -
Security
Misconfiguration
A8:2019 -
Injection
A10:2019-
Insufficient Logging
& Monitoring
A9:2019- Improper
Assets Management

22. © 2021 – Phil Wilkins – mp3monster.org
Providing an SDK
Sometimes an SDK may ease adoption for the common ways of using an API…
• Your API may use an approach less commonly used e.g. BSON, gRPC etc – why increase the
learning curve, provide an SDK that makes it easy
• Opportunity to incorporate additional metadata about the use of the API, by allowing the SDK to
capture additional information
• If your API needs metadata to describe the content being communicated, the SDK can determine
this for the consumer
• If you’re APIs have been defined using one of the lesser known notations e.g. YAML, an SDK can
reduce this as a possible barrier
• Making it easier to use your API, particularly for devices & mobile platforms ..
• Coding against a SDK means development or compile time we’re more likely to spot usage
errors (class mismatches etc etc)
• Using dependent libraries is something every developer learns very early on
There are tools that can make this process a lot simpler e.g.
• APIMatic
• APITools
• RESTUnited
• Swagger CodeGen
• AutoRest

23. Illustration of
beyond the payload

24. © 2021 – Phil Wilkins – mp3monster.org
Look at Google Maps … as an example of Good API
Provide both APIs and
SDKs to make adoption
easy

25. © 2021 – Phil Wilkins – mp3monster.org
Understanding the
consuming audience
Example content

26. © 2021 – Phil Wilkins – mp3monster.org
Explanation on how the
API use is paid for and
requirements to use
the API
Enabling
self service

27. © 2021 – Phil Wilkins – mp3monster.org

28. With more than 190,000 people, Capgemini is present in over 40 countries and
celebrates its 50th Anniversary year in 2018. A global leader in consulting, technology
and outsourcing services, the Group reported 2016 global revenues of EUR 12.5 billion.
Together with its clients, Capgemini creates and delivers business, technology and
digital solutions that fit their needs, enabling them to achieve innovation and
competitiveness. A deeply multicultural organization, Capgemini has developed its own
way of working, the Collaborative Business Experience™, and draws on Rightshore®, its
worldwide delivery model.
About Capgemini
Learn more about us at
www.capgemini.com
This message contains information that may be privileged or confidential and is
the property of the Capgemini Group.
Copyright © 2018 Capgemini. All rights reserved.
Rightshore® is a trademark belonging to Capgemini.
This message is intended only for the person to whom it is addressed. If you are not the intended recipient, you are not authorized to
read, print, retain, copy, disseminate, distribute, or use this message or any part thereof. If you receive this message in error, please
notify the sender immediately and delete all copies of this message.