SymfonyCon - Dilemmas and decisions..pdf

1. Dilemmas and decisions What we’ve learned designing the new Sylius API

2. Introduction 01 Photo by Mikhail Vasilyev on Unsplash

3. sylius.com 3

4. Certi fi cation 🎄

5. SYLIUSROCKS -30%

6. Paid OS Support

7. Modular SyliusPlus

8. sylius.com 8

9. sylius.com 9 Started in 2020 1.12 with AP 2.7 (since 31st of Oct) 1.13 stabilized with AP 3.0 🎉 ~100% of shop & ~70% of all coverage

10. Photo by Shane Aldendorff on Unsplash Decisions & consequences 02

11. Strategic design

12. sylius.com 12 ADRs

13. [short title of solved problem and solution] Status: [proposed | rejected | accepted | deprecated | … | superseded by ADR-0005] Date: [YYYY-MM-DD when the decision was last updated] Context and Problem Statement [Describe the context and problem statement] Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] [example | description | pointer to more information | …] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justi fi cation]. References [Link type] [Link to ADR] …

21. sylius.com 21 Conclusion?

22. sylius.com 22 GraphQL vs REST

23. 2020 -> GraphQL 🚀

24. Is it still?

27. Is it not?

28. sylius.com 28 ✔ Solves over fetching and under fetching By design ✔ Typed, nice documentation ? Sends everything with POST It is possible to do it with GET ✔ Gracefully deprecation of queries Which was not possible with default REST GraphQL

29. sylius.com 29 ✔ May solve over fetching and under fetching With spare fi elds sets and/or Vulcain ✔ Typed, nice documentation With OpenAPI ✔ Takes advantage of 20 years of web cache development Fake date institute ™ ✔ Gracefully deprecation of queries With OpenAPI REST

31. Resources design

32. sylius.com 32 State transitions

33. Case Let’s cancel an order!

34. sylius.com 34 Considered option #1 PATCH /api/orders/42/ { "state": "cancelled" }

35. sylius.com 35 Considered option #2 PATCH /api/orders/42/cancel {}

37. RESTful Archetypes Document /api/admin/orders/1 Store Client controlled /api/admin/orders/123 Collections Server controlled /api/admin/orders Controller /api/admin/orders/1/cancel Based on: REST API Design Rulebook by Mark Masse

38. sylius.com 38 Isn’t there a better way?

39. sylius.com 39 Solution? POST /api/orders-cancellation-requests/ {}

41. sylius.com 41 Calculated data

42. Case Cost of the shipment

43. Version #1 - Adding fi elds on entity class ShippingMethod { /** rest of methods */ public ?int $cost; // never used in app // serialized only when possible to count }

44. Version #2 - Read model class CartShippingMethod { public function __construct( public readonly string $code, public readonly ShippingMethodInterface $shippingMethod, public readonly int $cost ) { } }

45. Version #3 - Dynamic fi eld

46. public function normalize($object, $format = null, array $context = []) { Assert::keyNotExists($context, self::ALREADY_CALLED); $context[self::ALREADY_CALLED] = true; $data = $this->normalizer->normalize($object, $format, $context); $calculator = $this->shippingCalculators->get($object->getCalculator()); $data['price'] = $calculator->calculate( $shipment, $object->getConfiguration() ); return $data; } public function normalize($object, $format = null, array $context = []) { Assert::keyNotExists($context, self::ALREADY_CALLED); $context[self::ALREADY_CALLED] = true; $data = $this->normalizer->normalize($object, $format, $context); $calculator = $this->shippingCalculators->get($object->getCalculator()); $data['price'] = $calculator->calculate( $shipment, $object->getConfiguration() ); return $data; } public function normalize($object, $format = null, array $context = []) { Assert::keyNotExists($context, self::ALREADY_CALLED); $context[self::ALREADY_CALLED] = true; $data = $this->normalizer->normalize($object, $format, $context); $calculator = $this->shippingCalculators->get($object->getCalculator()); $data['price'] = $calculator->calculate( $shipment, $object->getConfiguration() ); return $data; } public function normalize($object, $format = null, array $context = []) { Assert::keyNotExists($context, self::ALREADY_CALLED); $context[self::ALREADY_CALLED] = true; $data = $this->normalizer->normalize($object, $format, $context); $calculator = $this->shippingCalculators->get($object->getCalculator()); $data['price'] = $calculator->calculate( $shipment, $object->getConfiguration() ); return $data; } Version #3 - Dynamic fi eld

48. High level API design

49. sylius.com 49 Uni fi cation of API

50. /api/products/ Admin & Shop served together

51. sylius.com 51 ✘ Available fi elds Complicated serialisation groups depending on logged in user ✘ Hard to de fi ne identi fi ers We have resigned from them later ✘ Requirement to de fi ne granular access control To now allow to access sensitive date for non-admins Findings

52. sylius.com 52 🛒 Shop has 72 endpoints 64% of read endpoints 🖊 Only 20% of resources have writable capabilities in shop 40% of them are never exposed in shop ⚙ Admin has 128 endpoints 52% of read endpoints Data

53. Option #1 - Admin & Shop pre fi xed /api/products/?admin

54. sylius.com 54 ✔ Available fi elds Depending on logged in user ✘ Seems wrong from the REST perspective If we add pre fi x to the URL ✘ Requirement to de fi ne granular access control To now allow to access sensitive date for non-admins Findings

55. Option #2 - Admin & Shop header split /api/products/ Accept: application/vnd.sylius-admin.api+json

56. sylius.com 56 ✔ Available fi elds Depending on logged in user ✔ REST compilant ✘ Requirement to de fi ne granular access control May be mitigated with Voters Findings ✘ Not easily supported By API Platform and Open API spec

57. Option #3 - Admin & Shop pre fi xed /api/shop/products/ /api/admin/products/

58. sylius.com 58 ✔ Available fi elds Depending on logged in user ✔/✘ REST compilant Disputable ✔ Straightforward access control Just with security con fi g Findings ✔ Easily supported By API Platform and Open API spec

60. sylius.com 60 API versioning

61. /api/v1 Old Admin API

62. #1 version /new-api/

63. sylius.com 63 URL based versioning /api/v2 Custom header X-Sylius-API-Version: 1 Accept header with an additional vendor information Accept: application/vnd.sylius.v1+json #2 version

67. sylius.com 67 But!

68. sylius.com 68 🔮 Versioning endpoints With sunset header 🔮 Vendor added to accept header application/vnd.sylius.v1+json 🔮 Deprecating endpoints, fi elds etc In documentation of Open API Future

69. API fl ow design

70. Case #1 Add to cart

71. Simple product { "product": “/api/products/42“, "quantity": 1 }

72. Con fi gurable product #1 { "product": “/api/products/42“, "productVariant": “/api/product-variants/42“, "quantity": 1 }

73. { "product": “/api/products/42“, “options": { "SIZE": “SIZE_L", "COLOR": “COLOR_BLUE" }, "quantity": 1 } Con fi gurable product #2

74. { "product": “/api/products/864“, "productVariant": “/api/product-variants/864“, "quantity": 1 } Let’s improve! { "product": “/api/products/42“, "quantity": 1 } Configurable product Simple product

75. Let’s improve! { "product": “/api/products/864“, "productVariant": “/api/product-variants/864“, "quantity": 1 } { "product": “/api/products/42“, "productVariant": “/api/product-variants/42“, "quantity": 1 } Configurable product Simple product

76. Let’s improve! { "product": “/api/products/42“, "productVariant": “/api/product-variants/42“, "quantity": 1 } Configurable product Simple product

77. Let’s improve! { "productVariant": “/api/product-variants/42“, "quantity": 1 } Configurable product Simple product

78. sylius.com 78 But what with options?

79. Price matrix in UI or Ask us

81. Case #2 Order details

82. Apply coupon

83. Apply coupon PATCH /ap i /v 2 /sho p /order s /TOKEN_VALU E /apply-coupon { "couponCode": “CHRISTMAS_SALE" }

84. Cart claiming & addressing

85. Cart claiming & addressing PATCH /ap i /v 2 /sho p /order s /TOKEN_VALUE/address { "email": “test@example.com”, "billingAddress": { "firstName": "Jane", "lastName": "Doe", "...": "..." } }

86. sylius.com 86 ✔ We are used to this separation Mockups “force” such design ✔ Addressing requires state machine transition While coupon appliance cart processing ✔ Di ff erent data required on di ff erent pages Reasoning?

87. What about order update?

88. Order update PUT /ap i /v 2 /sho p /order s /TOKEN_VALUE { "localeCode": “en_US” }

89. But it is just order drafting!

90. sylius.com 90 ✔ UI Mockups should not force any design decision We can preload data from more then one endpoint ✔ Don’t use state machine where there is none ✔ Either store data earlier or use partial update Changed attitude

91. PUT /ap i /v 2 /sho p /order s /TOKEN_VALUE/ { "email": “test@example.com”, "billingAddress": { "firstName": "Jane", "lastName": "Doe", "countryCode": "US", "street": “Baker Street 221B”, "city": “London", "postcode": "Doe" }, "couponCode": “CHRISTMAS_SALE" } Order update

93. Photo by Mikhail Vasilyev on Unsplash 03 Takeaways

94. sylius.com 94 Use ADRs And browse them from time to time Custom logic? New API resource! Let’s behave like a tax department! REST will be with us for the long time But GraphQL will be there as well Do not map HTML based websites to your API I know, it was obvious 😅

95. sylius.com 95 Thank you! Photo by Anthony DELANOIX on Unsplash @lukaszchrusciel @lchrusciel@mastodon.social @lchrusciel

SymfonyCon - Dilemmas and decisions..pdf

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

More from Łukasz Chruściel

More from Łukasz Chruściel (20)

Recently uploaded

Recently uploaded (20)

SymfonyCon - Dilemmas and decisions..pdf