Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

Designing Quality APIs

94 vues

Publié le

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.

Publié dans : Technologie
  • Soyez le premier à commenter

Designing Quality APIs

  1. 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. 2. 22DESIGNING QUALITY APIs • API? • Swagger Deprecated • REST Maturity Level • Quality API That Developers Love • Let’s See An Example • • • SummarySummary
  3. 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. 4. 44DESIGNING QUALITY APIs
  5. 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. 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. 7. 77DESIGNING QUALITY APIs API ? Simple classificationAPI ? Simple classification
  8. 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. 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. 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. 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. 12. 1212DESIGNING QUALITY APIs REST Maturity levelsREST Maturity levels
  13. 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. 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. 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. 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. 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. 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. 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. 20. 2020DESIGNING QUALITY APIs SWAGGER DEPRECATEDSWAGGER DEPRECATED 20192019
  21. 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. 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. 23. 2323DESIGNING QUALITY APIs
  24. 24. 2424DESIGNING QUALITY APIs Swagger Deprecated | Open API membersSwagger Deprecated | Open API members
  25. 25. 2525DESIGNING QUALITY APIs
  26. 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. 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. 28. 2828DESIGNING QUALITY APIs Swagger Deprecated | Swagger 2 vs Open Api 3Swagger Deprecated | Swagger 2 vs Open Api 3
  29. 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. 30. 3030DESIGNING QUALITY APIs Swagger Deprecated | ToolsSwagger Deprecated | Tools
  31. 31. 3131DESIGNING QUALITY APIs Quality API That developers love Quality API That developers love
  32. 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. 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. 34. 3434DESIGNING QUALITY APIs Quality API | SAP Hybris OCCQuality API | SAP Hybris OCC
  35. 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. 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. 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. 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. 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. 40. 4040DESIGNING QUALITY APIs Let’s take an ExampleLet’s take an Example https://github.com/embenzekri/moneytransfer
  41. 41. 4141DESIGNING QUALITY APIs Let’s take an Example | Swagger uiLet’s take an Example | Swagger ui
  42. 42. 4242DESIGNING QUALITY APIs embzenzekri@sqli.com Thank you for attention!Thank you for attention!
  43. 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

×