An updated look at API Design and what is involved.

1. API Design – More than just a Payload
Definition
Name
Phil Wilkins
OCI
November 2022

2. Speaker
Phil Wilkins
Cloud Developer Evangelist
2 Copyright © 2022, Oracle and/or its affiliates
Philip.Wilkins@Oracle.com
https://bit.ly/devrel-slack-emea @Phil Wilkins
mp3monster.org / cloud-native.info / oracle-integration.cloud
linkedin.com/in/philwilkins
github.com/mp3monster
@mp3monster

3. The following is intended to present ideas & application of
open technologies. It is intended for information purposes
only, and may not be incorporated into any contract. It is
not a commitment to deliver any material, code, or
functionality, and should not be relied
upon in making purchasing decisions. The development,
release, timing, and pricing of any features or functionality
described for Oracle’s products may change and remains at
the sole discretion of Oracle Corporation.
This presentation contains the thoughts and
ideas of this presenter & does not necessarily
represent the views of Oracle Corporation.
3 Copyright © 2022, Oracle and/or its affiliates

4. 4 Copyright © 2022, Oracle and/or its affiliates
APIs, more than a
Payload?

5. Good APIs – Apply everywhere …
5 Copyright © 2022, Oracle and/or its affiliates

6. The parts of Open API Specification (OAS) we focus on when developing
an API
6 Copyright © 2022, Oracle and/or its affiliates
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/

7. Copyright © 2022, Oracle and/or its affiliates
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
The parts of OAS we focus on when developing an API

8. 8 Copyright © 2022, Oracle and/or its affiliates
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
Extending the schema option to convey extra details

9. 9 Copyright © 2022, Oracle and/or its affiliates
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
Terms of Service – go look over there …

10. 10 Copyright © 2022, Oracle and/or its affiliates
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/
Security controls – not obvious …

11. Declaring Security Model - SecuritySchemes
11 Copyright © 2022, Oracle and/or its affiliates
Extract from the specification illustrating how
we can represent different security schemes
– simple and informative

12. 12 Copyright © 2022, Oracle and/or its affiliates
Does the API Spec
cover/reference
everything?

13. API Wall for External APIs
13 Copyright © 2022, Oracle and/or its affiliates
Authentication
&
Authorization
SDK
/
Code
Generator
Test
Framework

14. But my API is not for
external use!
14 Copyright © 2022, Oracle and/or its affiliates

15. 15 Copyright © 2022, Oracle and/or its affiliates
… will you be supporting your API for the rest
of your career or its life?
What about the impact of an API
Gateway on your API use?
Internal or External – your API will be looked at by
others

16. Internal API Gateways
16 Copyright © 2022, Oracle and/or its affiliates
We should be considering internal gateways to …
• Enforce rate limiting to avoid possible runway processes swamping you
with API calls
• Capture usage data for billing
• Creating points of abstraction
• Gateways 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)
These points are not easily defined in an API spec …
But can be supported by referenced documentation

17. Supporting Adoption and Change
17 Copyright © 2022, Oracle and/or its affiliates
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

18. API Wall for External APIs
18 Copyright © 2022, Oracle and/or its affiliates
Authentication
&
Authorization
SDK
/
Code
Generator
Test
Framework

19. API Wall for Internal APIs
19 Copyright © 2022, Oracle and/or its affiliates
Legalese
Authentication
&
Authorization
SDK
Test
Framework

20. 20 Copyright © 2022, Oracle and/or its affiliates
Still with me ?
Solving the problem …
bi-products & benefits

21. What to do ?
21 Copyright © 2022, Oracle and/or its affiliates
1. Create yourself a checklist like our “wall”, and decide what “bricks can help” in a situation
1. As an organization, agree common ways of providing the ‘bricks’
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, and debates about accountability)

22. API 1st – will help identify what is important and requires most support /
information
22 Copyright © 2022, Oracle and/or its affiliates
Feedback
Design
Build Package &
Deploy
Try Continuous
Test
Feedback
Run
Analyse
Feedback
Build Package &
Deploy
Try Continuous
Test
API Provider
API Consumer
Explanation to API first:
https://apievangelist.com/2020/03/09/what-is-api-first/

23. Being the next Elon Musk
23 Copyright © 2022, Oracle and/or its affiliates
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
Cloud Elements 2021 State of APIs report
https://offers.cloud-elements.com/2021-state-of-api-integration-report

24. APIs Are Business Critical
24 Copyright © 2022, Oracle and/or its affiliates

25. State of API Reports 2021
25 Copyright © 2022, Oracle and/or its affiliates
Cloud Elements 2021 State of APIs report
https://offers.cloud-elements.com/2021-state-of-api-integration-report

26. State of API Reports 2022
26 Copyright © 2022, Oracle and/or its affiliates
https://voyager.postman.com/doc/postman-state-of-the-api-2022.pdf
Tech consumers = ~50%

27. Better handle & communication on how your API will evolve and version
27 Copyright © 2022, Oracle and/or its affiliates

28. Don’t be the cause of a security issue
(better be the person who helped prevent one)
28 Copyright © 2022, Oracle and/or its affiliates
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

29. Providing an SDK
29 Copyright © 2022, Oracle and/or its affiliates
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 an SDK means development or compile time; we’re more likely to spot usage
errors (class mismatches 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

30. 30 Copyright © 2022, Oracle and/or its affiliates
Illustration of beyond the
payload

31. Look at Google Maps … as an example of Good API
31 Copyright © 2022, Oracle and/or its affiliates
Provide both APIs and SDKs
to make adoption easy

32. 32 Copyright © 2022, Oracle and/or its affiliates
Understanding the
consuming audience
Giving the bigger picture

33. Explanation on how the
API use is paid for and
requirements to use the
API
Enabling
self service

34. 34 Copyright © 2022, Oracle and/or its affiliates
Useful Stuff …

35. OCI Architecture Center -- Free Content & More
URLS are https://oracle.com/goto/...
Reference
Architectures
GitHub - DevRel
/ref-archs
Playbooks
/playbooks /gh-devrel
/deployed
Built & Deployed Live Labs
/labs
Tutorials
/tutorial
Blogs
Developer Open Source
Learning Videos Apex PaaS Community
GitHub - Oracle
/gh-oracle
Cloud Customer
Connect
/connect
/open
/dev
/paas
/apex
/blog
/youtube
Oracle Community
/community
GitHub - Samples
/gh-samples
URLS are https://oracle.com/goto/...
Linux & VM
Learning
/luna

36. 36
To be activated for this special promo:
• Join our Public Slack Workspace and contact
me
Always Free
Services you can use for unlimited time
Free credits you can use for additional OCI services
300$ 500$ in Oracle Cloud Credits
+
30-Day Free Trial
Oracle Cloud Free Tier – Special Promo
Try Always Free. No Time Limits.

37. 37
oracledevrel.slack.co
m
Join the dedicated Slack channel to be
part of the conversation and raise your
questions to our Experts:
Step 1: Access the Slack OracleDevRel
Workspace following this link:
https://bit.ly/devrel-slack-emea
Step 2: Search for Phil Wilkins
philip.wilkins@oracle.com
Join our public Oracle DevRel Workspace

38. Questions / Thank you
Copyright © 2022, Oracle and/or its affiliates
Phil Wilkins
Cloud Developer Evangelist
Philip.Wilkins@Oracle.com
bit.ly/devrel-slack-emea @Phil Wilkins
mp3monster.org /
cloud-native.info / oracle-integration.cloud
linkedin.com/in/philwilkins
github.com/mp3monster
@mp3monster