Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Igor Miniailo - Magento 2 API Design Best Practices

261 visualizaciones

Publicado el

Explaining the Best Practices of Magento API Design. Performed by Igor Miniailo at Khmelnytskyi Magento Meetup.

Publicado en: Internet
  • Sé el primero en comentar

Igor Miniailo - Magento 2 API Design Best Practices

  1. 1. © 2017 Magento, Inc. Page | 1 API Design Best practices Igor Miniailo Magento 2 Architect
  2. 2. © 2017 Magento, Inc. Page | 2
  3. 3. © 2017 Magento, Inc. Page | 3
  4. 4. © 2017 Magento, Inc. Page | 4 Why is API so crucial?
  5. 5. © 2017 Magento, Inc. Page | 5
  6. 6. © 2017 Magento, Inc. Page | 6
  7. 7. © 2017 Magento, Inc. Page | 7
  8. 8. © 2017 Magento, Inc. Page | 8 Semantic Versioning Version numbers are in the format MAJOR.MINOR.PATCH, where: – MAJOR indicates incompatible API changes – MINOR indicates backward-compatible functionality has been added – PATCH indicates backward-compatible bug fixes
  9. 9. © 2017 Magento, Inc. Page | 9 The backward compatibility policy applies to PHP code annotated with @api
  10. 10. © 2017 Magento, Inc. Page | 10 Public and Private code
  11. 11. © 2017 Magento, Inc. Page | 11 Public vs Private code Private code is not supposed to be used by third party modules, so, in most cases, its modifications will only trigger PATCH version bumps. Changes in public code always trigger MINOR or MAJOR version bumps.
  12. 12. © 2017 Magento, Inc. Page | 12 What examples of Public code Magento has? • PHP Interface (marked with @api) • PHP Class (marked with @api) • Javascript Interface (marked with @api) • Javascript Class (marked with @api) • Virtual Type (marked with @api) • URL paths • Console commands and their arguments • Less Variables & Mixins • Message queue topics and their data types • UI component declarations • Layout handles declared by modules • Events triggered by component (both static dynamic) • Schema of configuration types introduced by module • Structure of System Configuration fields used by module
  13. 13. © 2017 Magento, Inc. Page | 13 API vs SPI (Extension Points) A PHP Interface in Magento can be used several ways by the core product and extension developers. • As an API. is a set of interfaces and their implementations that a module provides to other modules • As a Service Provider Interface (SPI). is a set of interfaces that a module uses internally and allows their implementation by other modules. • As both. APIs and SPIs are not mutually exclusive.
  14. 14. © 2017 Magento, Inc. Page | 14 After the code is released, both API and SPI can be evolved in a backwards-compatible way. But both have their specific limitations.
  15. 15. © 2017 Magento, Inc. Page | 15
  16. 16. © 2017 Magento, Inc. Page | 16
  17. 17. © 2017 Magento, Inc. Page | 17
  18. 18. © 2017 Magento, Inc. Page | 18
  19. 19. © 2017 Magento, Inc. Page | 19
  20. 20. © 2017 Magento, Inc. Page | 20 We do not distinguish them separately. SPIs are annotated the same as APIs.
  21. 21. © 2017 Magento, Inc. Page | 21 Who decides whether interface/class belong to API or SPI? YOU
  22. 22. © 2017 Magento, Inc. Page | 22 Dependency Rules API If a module uses (calls) an API, it should be dependent on the MAJOR version. API dependency example { ... "require": { "magento/module-customer": "~100.0", // (>=100.0 <101.0.0) }, ... }
  23. 23. © 2017 Magento, Inc. Page | 23 Dependency Rules SPI If a module implements an API/SPI, it should be dependent on the MAJOR+MINOR version. SPI dependency example { ... "require": { "magento/module-customer": "~100.0.0", // (>=100.0.0 <100.1.0) }, ... }
  24. 24. © 2017 Magento, Inc. Page | 24 http://devdocs.magento.com/guides/v2.1/release-notes/backward- incompatible-changes-2.1.html
  25. 25. © 2017 Magento, Inc. Page | 25 Prohibited Code Changes
  26. 26. © 2017 Magento, Inc. Page | 26 • Interface/class removal • Public & protected method removal • Introduction of a method to a class or interface PHP - Prohibited Code Changes
  27. 27. © 2017 Magento, Inc. Page | 27 MagentoCatalogApiCategoryRepositoryInterface
  28. 28. © 2017 Magento, Inc. Page | 28 MagentoCatalogApiCategoryListInterface
  29. 29. © 2017 Magento, Inc. Page | 29 PHP - Prohibited Code Changes • Static function removal • Parameter addition in public methods • Parameter addition in protected methods
  30. 30. © 2017 Magento, Inc. Page | 30
  31. 31. © 2017 Magento, Inc. Page | 31 PHP - Prohibited Code Changes • Method argument type modification • Modification of types of thrown exceptions (unless a new exception is a subtype of the old one) • Constructor modification
  32. 32. © 2017 Magento, Inc. Page | 32 class ExistingClass { /** * @var NewDependencyInterface $newDependency */ private $newDependency; public function __construct( OldDependencyIntreface $oldDependency, $oldRequiredConstructorParameter, $oldOptinalConstructorParameter = null, NewDependencyInterface $newDependency = null ) { ... $this>newDependency = $newDependency ?: MagentoFrameworkAppObjectManager::getInstance() ->get(NewDependencyInterface::class); ... } public function existingFunction() { // Existing functionality ... // Use $this->newDependency wherever the new dependency is needed ... } }
  33. 33. © 2017 Magento, Inc. Page | 33 PHP - Prohibited Code Changes • Modifying the default values of optional arguments in public and protected methods • Removing or renaming constants
  34. 34. © 2017 Magento, Inc. Page | 34 The main rule is that backwards compatibility is more important than niceness and effort of the implementation.
  35. 35. © 2017 Magento, Inc. Page | 35 Coupling Between Objects Reaches Its Limit with a New Dependency
  36. 36. © 2017 Magento, Inc. Page | 36 We MUST do continuous Refactoring! Backward Compatibility should not be an excuse for not doing refactoring!
  37. 37. © 2017 Magento, Inc. Page | 37 Backward Compatible Fix *it works (most of the time), but code quality is far from good enough
  38. 38. © 2017 Magento, Inc. Page | 38 Good object oriented programming in the service layer is basically functional programming: • constructor injection • immutable state • single responsibility principle • uniform interfaces • value objects passed across services Bringing these concepts to an extreme leads to single-method, immutable objects.
  39. 39. © 2017 Magento, Inc. Page | 39
  40. 40. © 2017 Magento, Inc. Page | 40 Why execute but not __invoke?
  41. 41. © 2017 Magento, Inc. Page | 41 PHP 7 • Return Types • Scalar Type hinting
  42. 42. © 2017 Magento, Inc. Page | 42 Repositories In Magento 2 Repositories are considered as an implementation of Facade pattern which provides a simplified interface to a larger body of code responsible for Domain Entity management. The main intention is to make API more readable and reduce dependencies of business logic code on the inner workings of a module, since most code uses the facade, thus allowing more flexibility in developing the system.
  43. 43. © 2017 Magento, Inc. Page | 43 Repositories
  44. 44. © 2017 Magento, Inc. Page | 44
  45. 45. © 2017 Magento, Inc. Page | 45
  46. 46. © 2017 Magento, Inc. Page | 46 Good API design Don't make your client do anything you can do for them (this reduces the amount of boilerplate code your client will have)
  47. 47. © 2017 Magento, Inc. Page | 47 Headless Magento
  48. 48. © 2017 Magento, Inc. Page | 48 RESTful API
  49. 49. © 2017 Magento, Inc. Page | 49 Swagger http://devdocs.magento.com/guides/v2.2/rest/generate-local.html
  50. 50. © 2017 Magento, Inc. Page | 50 MSI Base Concept
  51. 51. © 2017 Magento, Inc. Page | 51 LSD * Load – Save – Delete
  52. 52. © 2017 Magento, Inc. Page | 52 2 Business operations – 1 API 1. Stock Setting (Import, Synchronization with ERP) 2. Stock Deduction (Checkout)
  53. 53. © 2017 Magento, Inc. Page | 53 Bad designed APIs could lead to Big issues
  54. 54. © 2017 Magento, Inc. Page | 54 The reason of DB Wait Lock on Checkout
  55. 55. © 2017 Magento, Inc. Page | 55 Reservation - the entity is used when the order is placed and we need to reserve some product quantity in stock. Reservations are append only operations and help us to prevent blocking operations and race conditions at the time of checkout. Reservation mechanism https://github.com/magento-engcom/msi/wiki/Reservations
  56. 56. © 2017 Magento, Inc. Page | 56 Order Placement – Step 1 France Warehouse SKU-1: 5qty EU Stock SKU-1: 15qty Italy Warehouse SKU-1: 10qty Raw data Index Reservations No records Available Qty: 15qty (data from index, empty reservations)
  57. 57. © 2017 Magento, Inc. Page | 57 Order Placement – Step 2 Action: Customer buys 5 products on frontend
  58. 58. © 2017 Magento, Inc. Page | 58 Order Placement – Step 3 France Warehouse SKU-1: 5qty EU Stock SKU-1: 15qty Italy Warehouse SKU-1: 10qty Raw data Index Reservations SKU-1: -5 Available Qty: 10qty (data from index 15, apply all reservations -5) Data is NOT changed Reservation has been added
  59. 59. © 2017 Magento, Inc. Page | 59 Order Placement – Step 4 Action: Admin makes a re-order 3 products out of 5 returned, and new order consists of 2 products
  60. 60. © 2017 Magento, Inc. Page | 60 Order Placement – Step 5 France Warehouse SKU-1: 5qty EU Stock SKU-1: 15qty Italy Warehouse SKU-1: 10qty Raw data Index Reservations SKU-1: -5 SKU-1: +3 Available Qty: 13qty (data from index 15, apply reservations -5+3) Data is NOT changed Reservation has been added
  61. 61. © 2017 Magento, Inc. Page | 61 Order Placement – Step 6 Action: Admin completes order. Re-index was run.
  62. 62. © 2017 Magento, Inc. Page | 62 Order Placement – Step 7 France Warehouse SKU-1: 3qty EU Stock SKU-1: 13qty Italy Warehouse SKU-1: 10qty Raw data Index Reservations SKU-1: -5 SKU-1: +3 SKU-1: +2 Available Qty: 13qty (data from index 13, apply reservations -5+3+2=0) Data is CHANGED Compensation Reservation has been added
  63. 63. © 2017 Magento, Inc. Page | 63 Order Placement – Step 8 Action: Reservation cleaning Looping through these reservations we could find reservations which in sum gives 0 (Zero) and remove them.
  64. 64. © 2017 Magento, Inc. Page | 64 Order Placement – Step 9 (like Step 1) France Warehouse SKU-1: 3qty EU Stock SKU-1: 13qty Italy Warehouse SKU-1: 10qty Raw data Index Reservations Available Qty: 13qty (data from index, empty reservations) Data is NOT changed Reservations have been removed No records
  65. 65. © 2017 Magento, Inc. Page | 65 API interface to test
  66. 66. © 2017 Magento, Inc. Page | 66 So, what’s about testing?
  67. 67. © 2017 Magento, Inc. Page | 67 What about fixtures?
  68. 68. © 2017 Magento, Inc. Page | 68
  69. 69. © 2017 Magento, Inc. Page | 69
  70. 70. © 2017 Magento, Inc. Page | 70 #MageConf, Kyiv 15-16 of December http://mageconf.com/
  71. 71. © 2017 Magento, Inc. Page | 71 Q & A @iminyaylo engcom@magent.com

×