[MGNLREST-529] DOC: How to collectively refer to Delivery API in v 3.x of REST module Created: 19/Oct/22  Updated: 27/Feb/23  Resolved: 27/Feb/23

Status: Closed
Project: Magnolia REST Framework
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Neutral
Reporter: Martin Drápela Assignee: Martin Drápela
Resolution: Obsolete Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File image-2022-10-19-10-38-15-118.png     PNG File image-2022-10-19-10-42-33-463.png     PNG File image-2022-10-19-10-45-24-924.png     PNG File image-2022-10-19-10-45-56-271.png     PNG File image-2023-02-27-09-44-52-478.png    
Issue Links:
Relates
relates to MGNLREST-522 Specify Norsu endpoint without Java c... Closed
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Date of First Response:
Epic Link: NorsuDocs: Endpoint documentation phase 1
Story Points: 1
Team: DeveloperX

 Description   

A bit of history about the collective name:

(https://documentation.magnolia-cms.com/display/DOCS57/Delivery+endpoint+API)

Delivery endpoint v2

Version 2 was introduced with Magnolia REST 2.1 and provides more flexibility. You can use it to define multiple endpoint configurations, deliver localized content and resolve references to nodes of other workspaces including assets and asset renditions.

See Delivery endpoint API v2.

Delivery endpoint v1

Version 1 was introduced with Magnolia REST 2.0. You can configure a single endpoint for your project.

In the 6.2 docs, we now only have v2 and refer to it like that:
(https://docs.magnolia-cms.com/product-docs/6.2/Developing/API/Delivery-API.html)

 

How to proceed after module version 3.0.0 is released?

Possibility A:
Start using Delivery API v3 

For module v 3.x+, I ve temporarily started using v3 for the docs update:
(and docs-internally as well for docu includables, see ex here: https://git.magnolia-cms.com/projects/MODULES/repos/rest/browse/docs/modules/api/partials/r_delivery-endpoint-v3-configuration.adoc )

Cons:  Internally, for continuity, v3 would in fact apply only to the JCR part:

not to the Norsu part:

Pros: Everybody will easily remember that v3 of the Delivery API can handle both, JCR + Norsu deliveries, whereas v2 can do only JCR.

Possibility B:
Use just Delivery API, don't add v3.

Cons: Breaks away from what we've been doing until now. 
**

Pros: Avoids that v2(JCR) / <????>(Norsu) referencing issue using v<number>.

 

 

 

 



 Comments   
Comment by Christopher Zimmermann [ 19/Oct/22 ]

I dont think the current changes indicate a jcrDeliveryEndpont_v3. A new major version would indicate to me that it is either incompatible with v2 functionaallity, that is it brings breaking changes, or that it brings major new functionality. It does not do either of these things so I would keep it as jcrDeliveryEndpoint_v2

I would not link the module version to the REST delivery endpoint version.

For the new norsu delivery endpoint, the users must specify a different class or `$type` to use it - ie "norsuDeliveryEndpoint". 
Here I am not 100% sure - but I would recommend starting with norsuDeliveryEndpoint_v2 as it has roughly the same functionality, saame configuration, and same response as the jcrDeliveryEndpoint_v2.

  • Certainly its no problem to start with v2.
  • In the present time having theme with the same version is helpful, since the functionality is comparable.
  • But I'm not sure about the future - the functionality may diverge... at which point the versions might not have much to do with each other. But my hunch is that the functionality will stay relativly similar for jcr and norsu endpoints.
Comment by Christopher Zimmermann [ 19/Oct/22 ]

Developers must specify the version of the endpoint. If they do not then when a new version comes with breaking changes it will break their projects.
(We did recently introduce that developer does not have to specify the class for the delivery endpoint, but this is going to be deprecated for the aabove reason.)

Generated at Mon Feb 12 07:00:46 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.