What we've learned designing new Sylius API
•
0 j'aime•110 vues
The document discusses the design of a new Sylius API. It began development in 2020 and has covered 100% of shop endpoints and 70% of all endpoints. Various options were considered for API design decisions like versioning, calculating dynamic fields, and handling admin vs shop resources. Architecture decision records were used to document choices. Based on lessons learned, REST was found to be better than GraphQL by default, and calculated data is best handled with read models rather than on entities. UI mockups should not dictate API design, and custom operations are best modeled with new resource endpoints.
Recommandé
Contenu connexe
Tendances
Tendances (20)
Similaire à What we've learned designing new Sylius API
Similaire à What we've learned designing new Sylius API (20)
Plus de Łukasz Chruściel
Plus de Łukasz Chruściel (18)
Dernier
Dernier (20)
What we've learned designing new Sylius API
- 1. Dilemmas and Dilemmas and decisions decisions What we’ve learned designing the What we’ve learned designing the new Sylius API new Sylius API
- 2. QUIZ QUIZ
- 8. Started in 2020 Started in 2020 1.12 with AP 2.7 1.12 with AP 2.7 (since 31st of Oct) 1.13 stabilized with AP 3.0 1.13 stabilized with AP 3.0 ~100% of ~100% of Shop endpoints Shop endpoints covered covered ~70% of all endpoints covered
- 11. ADRs ADRs
- 12. QUIZ QUIZ
- 13. Architecture Decision Records Architecture Decision Records [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 14. Architecture Decision Records Architecture Decision Records [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 15. Architecture Decision Records Architecture Decision Records [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 16. Architecture Decision Records Architecture Decision Records [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 17. Architecture Decision Records Architecture Decision Records [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 18. Architecture Decision Records Architecture Decision Records [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 19. Conclusion Conclusion Architecture Architecture Decision Decision Records FTW Records FTW [short title of solved problem and solution] Status: [proposed | rejected | ... ] Date: [YYYY-MM-DD] Context and Problem Statement Decision Drivers [driver 1, e.g., a force, facing concern, …] … Considered Options [option 1] Good, because [argument a] Bad, because [argument b] … Decision Outcome Chosen option: "[option 1]", because [justification]. References [Link type] [Link to ADR]
- 20. GraphQL vs REST GraphQL vs REST
- 22. Is it still? Is it still?
- 25. Is it not? Is it not?
- 26. GraphQL GraphQL Solves over fetching Solves over fetching and under fetching and under fetching By design
- 27. GraphQL GraphQL Sends everything with Sends everything with POST POST It is possible to do it with GET
- 29. GraphQL GraphQL Gracefully deprecation Gracefully deprecation of queries of queries Which was not possible with default REST
- 30. REST REST May solve over fetching May solve over fetching and under fetching and under fetching With sparefields sets and/or Vulcain
- 31. REST REST Takes advantage of 30 Takes advantage of 30 years of web cache years of web cache development development Fake data institute™
- 33. REST REST Gracefully deprecation Gracefully deprecation of queries of queries With OpenAPI and HTTP Headers
- 34. Quiz Quiz
- 35. Conclusion Conclusion REST was a better default REST was a better default for us for us
- 38. Case Case Let’s cancel an Let’s cancel an order! order!
- 39. Considered option #1 Considered option #1 PATCH /api/orders/42/ { "state": "cancelled" }
- 40. Considered option #2 Considered option #2 PATCH /api/orders/42/cancel {}
- 43. RESTful Archetypes RESTful Archetypes Document Document /api/admin/orders/1 Collections Collections Server controlled /api/admin/orders Store Store Client controlled /api/admin/orders/123 Controller Controller /api/admin/orders/1/cancel 1 Based on: REST API Design Rulebook by Mark Masse 1.
- 44. Isn’t there a better way? Isn’t there a better way?
- 45. Considered option #3 Considered option #3 POST /api/orders- cancellation-requests/ {}
- 46. QUIZ QUIZ
- 47. Conclusion Conclusion Express your operation as Express your operation as resources resources
- 49. Case Case Cost of the Cost of the shipment shipment
- 50. Version #1 - Adding fields on entity Version #1 - Adding fields on entity class ShippingMethod { /** rest of methods */ public ?int $cost; // not used in business code }
- 51. Version #2 - Read model Version #2 - Read model readonly class CartShippingMethod { public function __construct( public string $code, public ShippingMethodInterface $shippingMethod, public int $cost ) { } }
- 52. Version #3 - Dynamic field Version #3 - Dynamic field
- 53. Version #3 - Dynamic field Version #3 - Dynamic field
- 54. Version #3 - Dynamic field Version #3 - Dynamic field public function normalize( $object, $format = null, array $context = [] ) { // $data creation $calculator = $this->shippingCalculators->get($object- >getCalculator()); $data['price'] = $calculator->calculate( $shipment, $object->getConfiguration() ); return $data; }
- 55. QUIZ QUIZ
- 56. Conclusion Conclusion Read models are default Read models are default way to go way to go
- 57. High level API High level API design design
- 58. Unification of API Unification of API
- 59. Shop Shop 72 endpoints 72 endpoints 64% of read endpoints 64% of read endpoints 20% of resources have 20% of resources have writable capabilities writable capabilities Admin Admin 128 endpoints 128 endpoints 52% of read endpoints 52% of read endpoints 40% of them are never 40% of them are never exposed in shop exposed in shop
- 60. Option #1 Option #1 Admin & Shop served together Admin & Shop served together /api/products/
- 61. Findings Findings Available fields Available fields Complicated serialisation groups depending on logged in user Requirement to define granular access control Requirement to define granular access control To now allow to access sensitive date for non-admins Hard to define identifiers Hard to define identifiers We have resigned from them later Good from REST perspective Good from REST perspective
- 62. Option #2 Option #2 Admin & Shop suffixed Admin & Shop suffixed /api/products/?admin
- 63. Findings Findings Available fields Available fields Depending on logged in user Requirement to define granular access control Requirement to define granular access control To now allow to access sensitive date for non-admins Seems wrong from the REST perspective Seems wrong from the REST perspective If we add suffix for different representation
- 64. Option #3 Option #3 Admin & Shop header split Admin & Shop header split /api/products/ Accept: application/vnd.sylius- admin.api+json
- 65. Findings Findings Available fields Available fields Depending on logged in user Requirement to define granular access control Requirement to define granular access control May be mitigated with Voters REST compilant REST compilant Not easily supported Not easily supported By API Platform and Open API spec
- 66. Option #4 Option #4 Admin & Shop prefixed Admin & Shop prefixed /api/shop/products/ /api/admin/products/
- 67. Findings Findings Available fields Available fields Depending on logged in user Straightforward access control Straightforward access control Just with security config / / REST compilant REST compilant Disputable / / Easily supported Easily supported kind of by API Platform and fully by Open API spec
- 68. QUIZ QUIZ
- 69. Conclusion Conclusion Custom headers are the Custom headers are the way to go way to go But But Resource split was the Resource split was the best solution for us best solution for us
- 71. What we had What we had /api/v1
- 73. Option #1 Option #1 URL based versioning URL based versioning /api/v2
- 74. Option #2 Option #2 Accept header with version Accept header with version Accept: application/vnd.sylius.v1+json
- 75. Option #3 Option #3 Custom header Custom header X-Sylius-API-Version: 1
- 77. QUIZ QUIZ
- 80. Conclusion Conclusion API Evolution API Evolution Version in header Version in header We chose versioning in URL We chose versioning in URL
- 81. API flow design API flow design
- 82. Case #1 Case #1 Add to cart Add to cart
- 83. Simple product Simple product { "product": "/api/products/42", "quantity": 1 }
- 84. Configurable product #1 Configurable product #1 { "product": "/api/products/42", "productVariant": "/api/variants/42", "quantity": 1 }
- 85. Configurable product #2 Configurable product #2 { "product": "/api/products/42", "options": { "SIZE": "SIZE_L", "COLOR": "COLOR_BLUE" }, "quantity": 1 }
- 89. Simple & Configurable product Simple & Configurable product { "product": "/api/products/8", "productVariant": "/api/variants/42", "quantity": 1 }
- 90. Simple & Configurable product Simple & Configurable product { "productVariant": "/api/variants/42", "quantity": 1 }
- 91. But what with options? But what with options?
- 92. Price matrix in UI Price matrix in UI or or Ask us Ask us
- 93. Case #2 Case #2 Order details Order details
- 95. Apply coupon PATCH /api/orders/TOKEN_VALUE /apply-coupon { "couponCode": "CHRISTMAS_SALE" }
- 97. Cart claiming & addressing PATCH /api/ orders/TOKEN_VALUE/address { "email": "test@example.com", "billingAddress": { "firstName": "Jane", "lastName": "Doe", "...": "..." } }
- 98. Reasoning? Reasoning? We are used to this separation We are used to this separation Mockups “force” such design Different data required on Different data required on different pages different pages Addressing requires state Addressing requires state machine transition machine transition While coupon appliance cart processing
- 99. What about order update? What about order update?
- 101. But it is just order drafting! But it is just order drafting!
- 102. Changed attitude Changed attitude UI Mockups should not force UI Mockups should not force any design decision any design decision We can preload data from more then one endpoint Use partial update Use partial update Don’t use state machine Don’t use state machine where there is none where there is none
- 103. Order update Order update PUT /api/v2/shop /orders/TOKEN_VALUE/ { "email": "test@example.com", "billingAddress": { "firstName": "Jane", "lastName": "Doe", "...": "..." }, "couponCode": "CHRISTMAS_SALE" }
- 104. Conclusion Conclusion Don't let mockups force Don't let mockups force you API design you API design
- 105. Takeaways Takeaways Use ADRs Use ADRs And browse them from time to time REST will be with us for REST will be with us for the long time the long time But GraphQL will be there as well Custom logic? New API Custom logic? New API resource! resource! Let’s behave like a tax department! Do not map HTML based Do not map HTML based websites to your API websites to your API I know, it was obvious