This is a presentation I delivered in New York, last May 2st 2019

1. Styleguide for Designing Web APIs with
Oracle Apiary with Swagger & API
Blueprint
Oracle Code Berlin 2019. April 9th 2019
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. 03

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

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

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

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

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

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

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

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

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

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

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

17. 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/

18. 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/

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

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

21. 18
APIs are the cornerstone for Digital
Transformation. U better design them well
https://thermomix.com/
APIs are building blocks for Digital Transformation.
They enable different channels & create new
businesses.
Copyright https://medium.com/apis-and-digital-transformation/how-api-management-accelerates-digital-business-4ccea9b302df

22. 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 what you
designed
https://www.canva.com/learn/50-meticulous-style-guides-
every-startup-see-launching/

23. What should be included in the
styleguide
20
1. Context
2. Fundamentals
3. Design Principles and
Patterns
4. Management
5. Tools
6. Operational and
mainteincance
https://www.templatemonster.com/blog/create-brand-style-
guide/

26. 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/

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

28. 25
What’s next?

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

30. Here we go

31. 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=