Page tree
Skip to end of metadata
Go to start of metadata

Shop REST API

To be able to implement a great shopping experience modern front-end technology should be supported, e.g. AngularJS or similar. This is best achieved if the main shop functionality is provided by a REST API. The API should support the following methods

Product actions

Reading product data (Magnolia REST API)

// not useful for front-end clients:
GET /nodes/v1/shopProducts/[path_to_shop_products]/?depth=[depth]&excludeNodeTypes=[node,types,to,exclude]
// better (contains what is really needed):
GET /v1/shop/{shopName}/products?category={category}
  • Standard Magnolia REST API?
  • depth describes how many levels down in the JCR tree you want to go (from the starting point)
  • excludeNodeTypes is probably only necessary when you fetch all products right from the root > you can exclude "technical" nodes like rep:Activities,rep:system,rep:AccessControl...

NOTE: The standard "nodes" Magnolia REST endpoint does not really return what would be needed by a front-end app: Too much clutter, image uuids instead of links, cannot be limited to a category... Therefore a "products" method in the shop endpoint is more useful:

  • returns the list of products
  • optionally limited to the products of a category

Search...

TBD

Shopping cart actions

Getting the current users shopping cart

GET /v1/shop/{shopName}/carts/current
  • returns the shopping cart (including cart items)
  • returns a 404 if the there is no cart for the current user
  • shopName is currently ignored > looks like a bug in the shop module but won't hurt in this case

Creating a new shopping cart

POST /v1/shop/{shopName}/carts
  • creates a new shopping cart and stores it in the session (if no cart existed)
    see ShopUtil.setShoppingCartInSession()
  • simply returns the current cart
  • should it return an error if the cart already existed?
  • again: shopName is currently ignored

Updating the shopping cart

PUT /v1/shop/{shopName}/carts/current
  • updates the shopping cart, e.g. billing address etc.
  • should it also update the cart items? (easy? hard?)

Deleting the shopping cart

DELETE /v1/shop/{shopName}/carts/current
  • removes the shopping cart from session (after order is completed)
  • is probably not needed as this should be handled by the "save" command > see below

Saving the shopping cart, i.e. processing the order (Magnolia REST API)

POST /commands/v1/shop/processOrder
  • Standard Magnolia "command" REST endpoint call
  • custom "processOrder" command will then call other commands
    • save order in database (JCR) and remove it from users session
    • create invoice
    • create delivery slip
    • send contact mail (i.e. mail to shop owner, logistics)
    • send confirmation mail (i.e. mail to customer)
    • log order
  • should return the info to be displayed on the confirmation message

Cart item actions

If it's too complicated to implement cart item manipulations via the PUT /shoppingcart call, then additional methods need to be provided:

Adding a cart item

POST /v1/shop/{shopName}/carts/current/items
  • Adds cart item to cart
  • See ShopSigletonParagraphTemplateModel.addToCart()

Updating a cart item

PUT /v1/shop/{shopName}/carts/current/items/{itemName}?quantity={quantity}
  • Updates a cart item (quantity)
  • See ShopUtil.updateItemQuantity()
  • NOTE: Items in the Magnolia shopping cart have been referenced with the product id... and the index. Product id is usually good enough to identify the cart item. But since the Magnolia shop allows options (e.g. size, color...) two products with different options configuration can be added and will produce separate cart items. To simplify we're using the itemIndex now.

Delete a cart item

DELETE /v1/shop/{shopName}/carts/current/items/{itemName}
  • removes a cart item from the cart
  • See ShopSigletonParagraphTemplateModel.updateItemQuantity()
  • probably not needed > updating the quantity to 0 does exactly the same

 

Most of the functionality needed to implement this REST API already exists in ShopUtil. Some functionality however is placed in model classes. The shop module should now be refactored so that all of the functionality is placed in a service class and both the model classes and the REST API make use of this functionality. See  MSHOP-187 - Getting issue details... STATUS

Support for multiple languages

The dialogs (e.g. shopProduct) do not reflect the i18n settings. Adding a i18n:true to the title field and adding a mapping for the workspace and path did not have an effect. See  MSHOP-190 - Getting issue details... STATUS .

According to Antti Hietala's comments on https://documentation.magnolia-cms.com/display/DOCS/Language+configuration i18n support in content apps seems to be a generic issue. Therefore it is out of the scope of a shop module upgrade.

Configuration improvements

There is a whole series of problems with the shop setup:

  • MSHOP-183 - Getting issue details... STATUS
  • MSHOP-184 - Getting issue details... STATUS
  • MSHOP-189 - Getting issue details... STATUS
  • MSHOP-185 - Getting issue details... STATUS
    • Is the selection of a default price category really necessary? Wouldn't it be easier to simply use the first price category in none other has been selected for the cart? Setup currently is awkward as you create a shop where you should select a default price category which does not exist at that point yet.
    • However: Getting rid of the default price category selection in the shop config and instead simply selecting the first price category in the list might break the update path for some installations!

Fix support for multiple shops

Although multiple shops could theoretically be set up (especially once the config bugs above are fixed), the shop name is completely ignored when the carts are accessed. This means that when you run multiple shops in one Magnolia the carts will get mixed up. See  MSHOP-188 - Getting issue details... STATUS

When accessing a shopping cart the shop name needs to be placed as prefix in front of the "shoppingCart" session variable name. That should do the trick. At the same time the shopping cart variable name which is configurable in the shop setup (but ignored at runtime) can be removed. This should not have any negative effects on existing installations as it only affects runtime data.

There are other things which do not properly support a multi-shop setup and therefore need to be fixed:

  • MSHOP-192 - Getting issue details... STATUS

Other bugfixes

  • MSHOP-44 - Getting issue details... STATUS
    • Upgrade path: requires proper version handler task!
  • MSHOP-48 - Getting issue details... STATUS
    • test - does this bug really affect 2.x versions?
  • MSHOP-52 - Getting issue details... STATUS

Other improvements

  • MSHOP-194 - Getting issue details... STATUS
    When is the cart removed from the user session?
    • From the business point of view: It should be removed as soon as the cart is saved. This will prevent further manipulations on the cart.
    • From the technical point of view: It would be best if it would stick around until the confirmation page has been displayed.
  • MSHOP-191 - Getting issue details... STATUS
  • MSHOP-116 - Getting issue details... STATUS
  • MSHOP-115 - Getting issue details... STATUS
  • MSHOP-111 - Getting issue details... STATUS
  • MSHOP-121 - Getting issue details... STATUS
  • No labels