Sylius and API Platform integration is the project that we started in early 2020. Since then, we were working hard designing, delivering and adjusting our new API. We've learned a lot and during my presentation, I would like to share our findings. Why did we design our API this way? What were our heuristics and what did we achieve? How to design more complicated flows in API?

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]
…

14. [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]
…

15. [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]
…

16. [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]
…

17. [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]
…

18. [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]
…

19. [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]
…

20. [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

30. sylius.com
30
Conclusion?

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/
{}

40. sylius.com
40
Conclusion?

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

47. sylius.com
47
Conclusion?

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

59. sylius.com
59
Conclusion?

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

66. sylius.com
66
Conclusion?

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

80. sylius.com
80
Conclusion?

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

92. sylius.com
92
Conclusion?

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