[MGNLREST-517] Specify delivery endpoint version in clean way Created: 14/Oct/22  Updated: 23/Oct/23  Resolved: 20/Dec/22

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

Type: Story Priority: Neutral
Reporter: Christopher Zimmermann Assignee: Oanh Thai Hoang
Resolution: Not an issue Votes: 0
Labels: None
Σ Remaining Estimate: Not Specified Remaining Estimate: Not Specified
Σ Time Spent: 4.5h Time Spent: 4.5h
Σ Original Estimate: Not Specified Original Estimate: Not Specified

Attachments: PNG File definition-app.png     PNG File output-rest.png    
Issue Links:
Relates
relates to MGNLREST-522 Specify Norsu endpoint without Java c... Closed
Sub-Tasks:
Key
Summary
Type
Status
Assignee
MGNLREST-518 Implementation Sub-task To Do  
MGNLREST-519 Review Sub-task To Do  
MGNLREST-520 Pre-Integration QA Sub-task To Do  
MGNLREST-521 QA Sub-task To Do  
Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Release notes required:
Yes
Documentation update required:
Yes
Date of First Response:
Epic Link: Headless Phase 2
Team: DeveloperX

 Description   

As a developer I must somehow specify which version of the DeliveryEndpoint system I am using, I want to do that in a clean, simple to understand, and not java-oriented way.

Also, we have decided that we should not supply a default endpoint as we see that this will cause projects to break in the future when we introduce new versions of the default endpoint which will not be backwards compatible.

Notes:

Currently one has to specify the class (or rely on a default).

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition

The standard magnolia pattern for this would be to add a $type mapping with a simple name, like "jcrDeliveryEndpoint_v2". I think this would be an acceptible solution. However, consider if there might be a better way, keeping in mind that we will be introducing new versionss, like "v3", and we  might want to even introduce minor versions . like "3.2".

Would we want do do something like:

type: jcrDeliveryEndpoint
version: 3 

If we did introduce a new 'version' field, then we could actually consdier making the type/class a default since the developers projects would be safe since they are pinned on a specific version.

 

 

 



 Comments   
Comment by Oanh Thai Hoang [ 18/Oct/22 ]

Here is discovery output for simple approach as above discussion:

create new $type for new endpoint implementation / version

 

Output:

Sample annotation definition type: https://git.magnolia-cms.com/projects/MODULES/repos/rest/pull-requests?create&activeTab=compare-commits-tab&sourceBranch=refs%2Fheads%2FMGNLREST-517-sample&targetRepoId=591&targetBranch=refs%2Fheads%2Fmaster

 

Sample yaml config for norsu 

$type: norsuDeliveryEndpoint_v1 

Output in definition app

Output when executing rest

Comment by Jaroslav Simak [ 19/Oct/22 ]

czimmermann Yes, i suggest we use different $type annotations.

Comment by Christopher Zimmermann [ 20/Dec/22 ]

Based on the analysis we decided to keep this pattern for new versions of the endpoints.

 

$type: jcrDeliveryEndpoint_v2
$type: jcrDeliveryEndpoint_v3
$type: jcrDeliveryEndpoint_v4

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