This document provides an agenda for a presentation on designing web APIs with Oracle Apiary and Swagger & API Blueprint. The presentation covers introducing APIs and their growing importance, the need for an API style guide, key design principles like discoverability and longevity, and demonstrates designing APIs using Apiary.io. It emphasizes that APIs are products that need careful design for usability, consistency and to be durable for the long term.

1. Styleguide for Designing Web APIs with
Oracle Apiary with Swagger & API
Blueprint
Oracle Code New York 2019. May 21st
S&P Solutions
Rolando Carrasco
Email: rcarrasco@spsolutions.com.mx
Twitter: @borland_c
Blog: oracleradio.blogspot.com
Linkedin: linkedin.com/in/rolandocarrasco/
Blvd Manuel Avila Camacho #36-10
Lomas de Chapultepec CP 11000
+52 55 91721478

2. AGENDA
1. API. A brief introduction.
2. API Context. The momentum.
3. API Styleguide
4. API Design principles.
5. DEMO. Apiary.io CLI, Dredd utilities to validate your API Design.
Live Demo. Live Coding.

3. S&P Solutions
Part of our work. Published books.
02

4. S&P Solutions 03
http://oracle-integration.cloud/
(2017)
New
http://apiplatform.cloud/
(2018)
Technical
Reviewer
Part of our work. Published books.

5. S&P Solutions
Oracle ACE. Red Expert Alliance. Groundbreaker Ambassador.
04
http://www.oracle.com/technetwork/community/oracle-ace/index.html
https://www.redexpertalliance.com/map-page/
https://blogs.oracle.com/developers/ne
w-developer-champion-program

6. Digital Transformation turned me
speachless. Thank u APIs!!!
05

7. But…are we living on
a hAPI world?
What do u think?
06

8. Are we living on a
hAPI world?
What do u think?
07
https://www.programmableweb.com/news/research-shows-interest-providing-apis-still-
high/research/2018/02/23?_lrsc=deb9ff17-8477-4d0e-9f43-9c050e3deb83

9. APIs here, there and everywhere.
08
https://www.gizmodo.com.au/2015/11/is-australia-ready-for-a-more-connected-world/

10. Ultimately, what is an API?
09
1. First of all we are talking about Web APIs during this
presentation. That is our interest for the upcoming 45
minutes
2. What is the relationship with:
• Web Services – REST or SOAP
• Services
• Microservices
• Functions

11. 10
(APIs = Web Services = Services = MicroService = Function
???)

12. 11
They are not the same thing.
Not …at all. They look alike,
but are different things.
https://streetsmartbrazil.com/different-part-2/

13. 12
They share the protocol, the interface.
But ultimately, they are intended for
different purposes and things.
HTTPS/XML/JSON
HTTPS/XML/JSON
HTTPS/XML/JSON
HTTPS/XML/JSON
MICROSERVICE A
MICROSERVICE B
SERVICE X
WEB SERVICE Y

14. Key elements to take care about our
APIs
13
1. While service orientation is targeted to reduce costs,
through services reusability, APIs are targeted to
generate money. External APIs may have that purpose.
2. An API is a product for your company. It needs to be
well designed, well presented, well documented
3. It has to be designed to be durable. For longevity
and not ephimeral

15. 14
That is why we need Design Principles.
http://slideplayer.com/slide/7571761/

16. 15
It’s your product. C’mon! Do
not hesitate on good design.
http://thjomas.com/39-shocking-famous-product-designers-photo-design/famous-product-designers-youtube-shocking-photo-design/

17. 15
Good APIs are
like love at first
sight.
• Simplicity (Flexibility-Usability Trade-off)
• Self-Explanatory
• Consistency
• Forgiveness
https://api-as-a-product.com/articles/hierarchy-api-design-principles/
http://thjomas.com/39-shocking-famous-product-designers-
photo-design/famous-product-designers-youtube-shocking-
photo-design/

18. 16
We need to build ready-to-use APIs.
http://www.campbellsoup.ca/en-ca/products/campbells-broths/campbells-ready-to-use-vegetable-
broth

19. 17
API First, Contract First, Design First!!
http://www.campbellsoup.ca/en-ca/products/campbells-broths/campbells-ready-to-use-vegetable-broth
Really??

20. Styleguide
19
1. It is normal to start with
one API , but then? You will
not stop creating and
mantaining
2. You need a styleguide to
follow. You need uniformity
3. You need a tool to validate
that the APIs are in
conform to your
styleguide
https://www.canva.com/learn/50-meticulous-style-guides-
every-startup-see-launching/

23. Eight APIs design principles…and one
suggestion
23
1. Discoverability
2. Adaptability
3. Abstraction
4. Versioning
5. Standardized API Contract
6. Autonomy
7. Longevity
8. Naming Convention (resources,
response codes, parameters, etc)
And one suggestion: Forgiveness…
“Learn to Design for Developers
and
for non-Developers.”
http://apievangelist.com/2018/05/08/api-design-either-
provider-does-the-work-or-the-consumer-does-the-work/

24. 24
But…where can I design good APIs?

25. 25
What’s next?

26. 26
What’s next?
Let’s demonstrate it
using Apiary.io

27. Here we go

28. References
28
1. Apiary styleguide
https://docs.oracle.com/cloud/apiary/tools/style-
guide/index.html
2. CLI reference
https://docs.oracle.com/cloud/apiary/tools/apiary-cli/
3. Video
https://www.youtube.com/watch?v=Jv4FCl6JmWI&t=