SymfonyCon - Dilemmas and decisions..pdf

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

2.
Introduction 01 Photo by MikhailVasilyev 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.12with AP 2.7 (since 31st of Oct) 1.13 stabilized with AP 3.0 🎉 ~100% of shop & ~70% of all coverage

10.
Photo by ShaneAldendorff on Unsplash Decisions & consequences 02

11.
Strategic design

12.
sylius.com 12 ADRs

13.
[short title ofsolved 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] …

14.

15.

16.

17.

18.

19.

20.

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 overfetching 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 solveover 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

30.

31.
Resources design

32.
sylius.com 32 State transitions

33.
Case Let’s cancel anorder!

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 abetter way?

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

40.

41.
sylius.com 41 Calculated data

42.
Case Cost of theshipment

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

47.

48.
High level APIdesign

49.
sylius.com 49 Uni fi cation of API

50.
/api/products/ Admin & Shopserved together

51.
sylius.com 51 ✘ Available fi elds Complicated serialisationgroups 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 has72 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 onlogged 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 onlogged 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 onlogged in user ✔/✘ REST compilant Disputable ✔ Straightforward access control Just with security con fi g Findings ✔ Easily supported By API Platform and Open API spec

59.

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 Customheader X-Sylius-API-Version: 1 Accept header with an additional vendor information Accept: application/vnd.sylius.v1+json #2 version

66.

67.
sylius.com 67 But!

68.
sylius.com 68 🔮 Versioning endpoints Withsunset 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 tocart

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 withoptions?

79.
Price matrix inUI or Ask us

80.

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 areused 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 orderupdate?

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

89.
But it isjust order drafting!

90.
sylius.com 90 ✔ UI Mockupsshould 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

92.

93.
Photo by MikhailVasilyev on Unsplash 03 Takeaways

94.
sylius.com 94 Use ADRs And browsethem 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 byAnthony DELANOIX on Unsplash @lukaszchrusciel @lchrusciel@mastodon.social @lchrusciel

SymfonyCon - Dilemmas and decisions..pdf

More Related Content

Similar to SymfonyCon - Dilemmas and decisions..pdf

More from Łukasz Chruściel

Recently uploaded

SymfonyCon - Dilemmas and decisions..pdf