Building quality APIs is a key success factor into integrating distributed systems. A well designed API is technology agnostic, easy to use, and easy to evolve, this can only be achieved by using tools and well defined standards and principles. First we will present how Swagger started to address APIs definitions using the design first approach, and how it evolved into the Open API specification. Furthermore we will describe the REST maturity model and compare it with a more pragmatic approach, where guidelines inspired by Apigee's Web API Design book are presented. Finally a demonstration of a sample REST API using Open API, can be found in https://github.com/embenzekri/moneytransfer.

1. 11DESIGNING QUALITY APIs
DESIGNING QUALITYDESIGNING QUALITY
APIsAPIs
EL MAHDI BENZEKRI | Full Stack DeveloperEL MAHDI BENZEKRI | Full Stack Developer
20192019
elmahdi.benzekri@gmail.com

2. 22DESIGNING QUALITY APIs
• API?
• Swagger Deprecated
• REST Maturity Level
• Quality API That Developers Love
• Let’s See An Example
•
•
•
SummarySummary

3. 33DESIGNING QUALITY APIs
• API?
• swagger depracated
• REST Maturity level
• Implementation biais in representation
•
•
•
SummarySummary
Teleportation?Teleportation?
Time travel?Time travel?
Antigravity?Antigravity?
SystemsSystems
integrationintegration
UnbreakableUnbreakable
passwordspasswords
True AITrue AI

4. 44DESIGNING QUALITY APIs

5. 55DESIGNING QUALITY APIs
• Communication across the network
• Get data from the server
• fast
• secure
• easy to use
•
API ? Not an important problemAPI ? Not an important problem

6. 66DESIGNING QUALITY APIs
• Software is hard to change
• It’s complicated
• It’s permeated with assumptions
• When you have done something you learn how to do it better
• Software is hard to integrate
• Basic API features are missing
• It’s n^2-n problem
• Payment, ERP, bookings, governemental APIs…
API ? Important problemAPI ? Important problem

7. 77DESIGNING QUALITY APIs
API ? Simple classificationAPI ? Simple classification

8. 88DESIGNING QUALITY APIs
• Procedure oriented
/getOrder
/prd/mobile-
1.0/isUpdateRequired/uk/en/ios/5.12
.0
•
• Similar to programming libraries
• APIs are all different
•
•
API ? 2 dominant stylesAPI ? 2 dominant styles
• Entity oriented
/orders
/updates?
country=ul&lang=en&terminal=ios&ter
minalVersion=5.12
•
•
•
• Similar to database schema
• APIs are all the same

9. 99DESIGNING QUALITY APIs
• « Attack » major problems
• If you don’t agree on technology, you didn’t agree on goals
• Uniform API
• Uniform model
• Free of implementation assumptions
• Built on top of Universal api: HTTP, but
• REST oxymoron, how to do query? Versioning ?
•
•
API ? What are the goalsAPI ? What are the goals

10. 1010DESIGNING QUALITY APIs
• Fundamental concept: creating relationships between entities in
different apps
• https://www.nespresso.com/ecapi/products/v2/uk/b2c/ZXJwLnVrLmIyYy
9wcm9kLzczMTAuMjA=?language=en
{
"id": "7439.40",
"name": "Roma",
"urlFriendlyName": "roma-coffee-capsule",
"category": "Intenso",
}
API ? Identity and relationshipsAPI ? Identity and relationships

11. 1111DESIGNING QUALITY APIs
•
•
• https://www.nespresso.com/ecapi/products/v2/uk
/b2c/ZXJwLnVrLmIyYy9wcm9kLzczMTAuMjA=?
language=en
{
"id": "7439.40",
"name": "Roma",
"urlFriendlyName": "roma-coffee-capsule",
"category": "Intenso",
"trackingId": "f4e22",
}
API ? Identity and relationshipsAPI ? Identity and relationships
•
•
• https://www.nespresso.com/ecapi/products/v2/7439.4
0?language=en&country=uk&channel=b2c
{
"id": "erp.uk.b2c/prod/7439.40",
"name": "Roma",
"urlFriendlyName": "roma-coffee-capsule",
"category": "categories/1234",
"trackingId":
"https://api.google.com/products/f4e22",
}

12. 1212DESIGNING QUALITY APIs
REST Maturity levelsREST Maturity levels

13. 1313DESIGNING QUALITY APIs
• REST coined by Roy Fielding’s in his Ph.D: Design of Network-based Software
Architectures.
• Architecture Style
• Technology agnostic
• Future of integrations
• Built on universal protocol: HTTP
REST Maturity levelsREST Maturity levels

14. 1414DESIGNING QUALITY APIs
• be careful, RESTifarians can be extremely meticulous when discussing the finer points of REST
• The API’s job is to make the developer as successful as possible
•
•
•
•
•
• what is the design with optimal benefit for the app developer?
Let’s be a Pragmatist..
REST Maturity levels | Are you a Pragmatist or a RESTafarian?REST Maturity levels | Are you a Pragmatist or a RESTafarian?

15. 1515DESIGNING QUALITY APIs
• Get Closer to REST and away from RPC
• Rigidity?
• Do we really need to invest in level 3?
• Level 2 is enough
• Remember we are Pragmatists
•
•
REST Maturity levels | Maturity LevelsREST Maturity levels | Maturity Levels
• Req/Resp Examples https://blog.goodapi.co/api-maturity-fb25560151a3

16. 1616DESIGNING QUALITY APIs
• RPC style
• single endpoint service multiple
resources
• Use HTTP as transportation layer
REST Maturity levels | Level 0 - The Swamp of POXREST Maturity levels | Level 0 - The Swamp of POX

17. 1717DESIGNING QUALITY APIs
• Split endpoints by
resources
• Introduce the notion
of identity
REST Maturity levels | Level 1 - ResourcesREST Maturity levels | Level 1 - Resources

18. 1818DESIGNING QUALITY APIs
• POST, GET, PUT, DELETE, PATCH
• Tuneling when method is not accepted : X-HTTP-METHOD-Override
• web proxy that disallows PUT and PATCH ?
https://twitter.com/stauffermatt/status/586510133296934913
•
•
REST Maturity levels | Level 2 – HTTP verbsREST Maturity levels | Level 2 – HTTP verbs

19. 1919DESIGNING QUALITY APIs
• HATEOAS to deal with discovering the possibilities of the API
• Propose what to do next
• it allows the server to change its URI scheme without breaking clients.
REST Maturity levels | Level 3 - Hypermedia controlsREST Maturity levels | Level 3 - Hypermedia controls

20. 2020DESIGNING QUALITY APIs
SWAGGER DEPRECATEDSWAGGER DEPRECATED
20192019

21. 2121DESIGNING QUALITY APIs
• Complementary
• Swagger is the API definition (and tools), REST is the architecture style
• Better question: REST vs SOAP and Swagger vs RAML, API Blueprint, and WSDL 2.0
• A Swagger API is not (always) RESTful - neither in definition nor in spirit.
•
Swagger Deprecated | REST vs SwaggerSwagger Deprecated | REST vs Swagger

22. 2222DESIGNING QUALITY APIs
• https://www.openapis.org/
• Open API when referring to the spec
• Swagger means the tools
• Bottom-up: started by solving real problems
• Partners from 9 to 32, it’s important to have a standard way to create APIs
• Spec Github: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
•
•
Swagger Deprecated | Open APISwagger Deprecated | Open API

23. 2323DESIGNING QUALITY APIs

24. 2424DESIGNING QUALITY APIs
Swagger Deprecated | Open API membersSwagger Deprecated | Open API members

25. 2525DESIGNING QUALITY APIs

26. 2626DESIGNING QUALITY APIs
• Spec -> Contract!!
• Tackle old solutions issues: corba -> Wsdl/wadl: http://wiki.c2.com/?WhatsWrongWithCorba
• Google uses Open api in front but GRPC internally, OAI support in gRPC?
• GitHub provides one nice model of a documented API: https://developer.github.com/v3/
• Docs and lot of docs
• Specs can drive mocks
Swagger Deprecated | Open API why now ?Swagger Deprecated | Open API why now ?

27. 2727DESIGNING QUALITY APIs
• Specs can also power:
• Test generation
• Traffic classification
• Runtime validation
• SDK generation
• Server-side code
• OATTS In npm.org
• And more…
Swagger Deprecated | Specs powerSwagger Deprecated | Specs power

28. 2828DESIGNING QUALITY APIs
Swagger Deprecated | Swagger 2 vs Open Api 3Swagger Deprecated | Swagger 2 vs Open Api 3

29. 2929DESIGNING QUALITY APIs
• Format Changes
• YAML should be 1.2
• Github Flavored Markdown will be replaced with
CommonMark
• supports more of JSON Schema (oneOf, anyOf,
not, nullable, deprecated, writeOnly)
•
• URL structure
• Multiple URLs
• path templating is now allowed
• no longer allowed to define a request body
for GET and DELETE (more RESTful)
Swagger Deprecated | Swagger 2 vs Open Api 3Swagger Deprecated | Swagger 2 vs Open Api 3
• Components Changes
• responses (existing)
• parameters (existing)
• examples (new)
• requestBodies (new)
• headers (new)
• links (new)
• callbacks (new)
• schemas (updated)
• securitySchemes (updated)
https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

30. 3030DESIGNING QUALITY APIs
Swagger Deprecated | ToolsSwagger Deprecated | Tools

31. 3131DESIGNING QUALITY APIs
Quality API
That developers
love
Quality API
That developers
love

32. 3232DESIGNING QUALITY APIs
• DDD for Documentation driven development
• Patterns:
• Re-use don’t re-invent
• Resource oriented
• Names matter
• When in doubt, do what’s best for developers
Quality APIQuality API
• If:
• Focus on network communication: ease of use,
match implementation
• Focus on important problem: idependence from
technology, resilience to change
•

33. 3333DESIGNING QUALITY APIs
• Uses swagger v2: https://help.hybris.com/6.7.0/hcd/99783546e09949e2b4bf27795b889464.html
• Starting with v2, OCC will not use sessions anymore, finally stateless.
• Complex paths: POST
https://localhost:9002/rest/v2/wsTest/users/username@email.com/carts/0000012/entries?
code=12345&qty=2
• REST Maturity level ? No HATEAOS
• POST /users/{userId}/carts/{cartId}/save, why no use PUT without /save ? Procedural mindset..
Quality API | SAP Hybris 6.x OCCQuality API | SAP Hybris 6.x OCC

34. 3434DESIGNING QUALITY APIs
Quality API | SAP Hybris OCCQuality API | SAP Hybris OCC

35. 3535DESIGNING QUALITY APIs
• 2 base URLs per resource
• Plural nouns and concrete names, products instead of
items
• force the verbs out of your base URLs.
• getAllOrder or getOrdersBy => /orders, /orders/id
• orders/id/save => PATCH /orders/id
Quality API | Nouns are good; verbs are bad, plurals are better thanQuality API | Nouns are good; verbs are bad, plurals are better than

36. 3636DESIGNING QUALITY APIs
• providing context and visibility
• Use of HTTP status codes
• Message for people and message for developers
• Error code to track the details
Quality API | Handling errorsQuality API | Handling errors

37. 3737DESIGNING QUALITY APIs
• simple ordinal number
• Maintain at least one version back.
• Give developers at least one cycle to react before
obsoleting a version.
• version and format be in URLs or headers?
Quality API | VersioningQuality API | Versioning

38. 3838DESIGNING QUALITY APIs
• Give just the needed information
• Add optional fields in a comma-delimited list
• paginate objects in a database with offset and
limit
Quality API | Pagination and partial responseQuality API | Pagination and partial response
• LinkedIn
/people:(id,first-name,last-name,industry)
• Facebook
/joe.smith/friends?fields=id,name,picture
• Google
?fields=title,media:group(media:thumbnail)

39. 3939DESIGNING QUALITY APIs
• to overcome the domain knowledge hurdle
• provide the platform-specific code
• Abstract the API complexity
• To market your API to a specific community and
outdo competitors
Quality API | Complement with an SDKQuality API | Complement with an SDK
• Yahoo! http://developer.yahoo.com/social/sdk/
• Paypal
https://cms.paypal.com/us/cgi-bin/?cmd=_rendercontent&c
• Adyen:
https://docs.adyen.com/developers/checkout/web
-sdk

40. 4040DESIGNING QUALITY APIs
Let’s take an ExampleLet’s take an Example
https://github.com/embenzekri/moneytransfer

41. 4141DESIGNING QUALITY APIs
Let’s take an Example | Swagger uiLet’s take an Example | Swagger ui

42. 4242DESIGNING QUALITY APIs
embzenzekri@sqli.com
Thank you for attention!Thank you for attention!

43. 4343DESIGNING QUALITY APIs
•
• Thesis: Architecture Styles and Design of Network based Software – UCI
• Book: The Richardson Maturity Model
• Book: REST in Practice: Hypermedia and Systems Architecture
• https://martinfowler.com
• https://openapis.org
• Book: Web API Design Crafting Interfaces that Developers Love
• Google Talks in Google Cloud Platform Youtube chanel
• https://smartbear.com
• References