This is the presentation I delivered during the Oracle Groundbreakers Tour 2019.

1. Styleguide for Designing Web APIs with
Oracle Apiary with API Blueprint
Oracle Groundbreakers Tour. Buenos Aires 06-
AGO-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. S&P Solutions
Our Books
03
New
Technical
Reviewer

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

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

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

26. 25
What’s next?

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

28. Here we go

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