API Design – More than just a Payload Definition

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

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

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.

APIs, more than a
Payload?

Good APIs – Apply everywhere …

The parts of Open API Specification (OAS) we focus on when developing
an API
Thanks to API Handyman
(Arnaud Lauret)
http://openapi-map.apihandyman.io/

Copyright © 2022, Oracle and/or its affiliates
(Arnaud Lauret)
The parts of OAS we focus on when developing an API

(Arnaud Lauret)
Extending the schema option to convey extra details

(Arnaud Lauret)
Terms of Service – go look over there …

(Arnaud Lauret)
Security controls – not obvious …

Declaring Security Model - SecuritySchemes
Extract from the specification illustrating how
we can represent different security schemes
– simple and informative

Does the API Spec
cover/reference
everything?

API Wall for External APIs
Authentication
&
Authorization
SDK
/
Code
Generator
Test
Framework

But my API is not for
external use!

… 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

Internal API Gateways
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

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

API Wall for External APIs
Authentication
&
Authorization
SDK
/
Code
Generator
Test
Framework

API Wall for Internal APIs
Legalese
Authentication
&
Authorization
SDK
Test
Framework

Still with me ?
Solving the problem …
bi-products & benefits

What to do ?
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)

API 1st – will help identify what is important and requires most support /
information
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/

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
Cloud Elements 2021 State of APIs report
https://offers.cloud-elements.com/2021-state-of-api-integration-report

APIs Are Business Critical

State of API Reports 2021
Cloud Elements 2021 State of APIs report
https://offers.cloud-elements.com/2021-state-of-api-integration-report

State of API Reports 2022
https://voyager.postman.com/doc/postman-state-of-the-api-2022.pdf
Tech consumers = ~50%

Better handle & communication on how your API will evolve and version

Don’t be the cause of a security issue
(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

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

Illustration of beyond the
payload

Look at Google Maps … as an example of Good API
Provide both APIs and SDKs
to make adoption easy

Understanding the
consuming audience
Giving the bigger picture

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

Useful Stuff …

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

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

API Design – More than just a Payload Definition

API Design – More than just a Payload Definition

More Related Content

Similar to API Design – More than just a Payload Definition (20)

More from Phil Wilkins (20)

Recently uploaded (20)

API Design – More than just a Payload Definition

Editor's Notes