[MGNLREST-152] Configure multiple delivery endpoints in separate modules Created: 20/Nov/17  Updated: 09/Apr/18  Resolved: 30/Jan/18

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

Type: Story Priority: Major
Reporter: Christopher Zimmermann Assignee: Dai Ha
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: 0d
Time Spent: 11d 4.5h
Original Estimate: 7d 3h

Issue Links:
dependency
is depended upon by MGNLREST-158 TourFinder endpoint overlaps newly re... Closed
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: REST Phase2
Sprint: Saigon 129, Saigon 130, Saigon 131, Saigon 132
Story Points: 13

 Description   

It should be possible to configure endpoint definitions separtately (for example with separate YAML files) which can be in separate modules. - It should be possible to work with them in the same way as defintitions for apps or virtualURI's.

Currently one can only define one delivery endpoint, which can be decorated. If more than one definition is supplied, then only one of them is used.

Some open questions:

  • Will these delivery endpoints be in the same registry as the existing endpoints?
  • Will these delivery endpoints still be routed under [context]/.rest/delivery/[my-new-delivery-endpiont] ?


 Comments   
Comment by Mikaël Geljić [ 10/Jan/18 ]
  • Yes, same registry
  • I suggest to route all endpoints under [context]/.rest/[endpoint-configured-relative-path]
    • because multiple registrations will be possible for all endpoints, not just delivery ones
    • and because the dynamic part must be the basepath (from resteasy perspective);
  • This means the default path for anonymous delivery becomes a convention.
    • if you configure your endpoint under a delivery folder, you will get automatic anonymous access
    • if not, you are opting-out and must manage URI security specifically
Comment by Christopher Zimmermann [ 17/Jan/18 ]

So the endpoint url would then always be the path to the endpoint file, instead of /.rest/delivery/?
it will work like this?:

File path delivery.yaml
/.rest/delivery/tours/v1

File path sooper.yaml
/.rest/sooper/tours/v1 (I need to configure the WEB ACCESS manually)

File path /delivery/imfree.yaml
/.rest/delivery/imfree/tours/v1 (Is this correct?)
In this new case...
/.rest/delivery/imfree would be nonsense - ie not available? right?

Comment by Dai Ha [ 17/Jan/18 ]

I had a PR which implements below behaviors:

/module_name/restEndpoints/delivery/def_v2.yaml ->

{context}/.rest/delivery/def/v2 --> no need to re-configure web access
/module_name/restEndpoints/p1/p2/p3/def_v1.yaml -> {context}

/.rest/p1/p2/p3/def/v1
/module_name/restEndpoints/p1/p2/p3/defv1.yaml ->

{context}/.rest/p1/p2/p3/defv1
/module_name/restEndpoints/def_v1.yaml -> {context}

/.rest/def/v1
/module_name/restEndpoints/defv1.yaml ->

{context}/.rest/defv1

Team had decided to support multiple endpoints for a new endpoint class "info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpoint", each endpoint definition will bind to one workspace. This helps the old ones work as is.
In additional, new attribute "endpointPath" was introduced in definition for flexibility to by-pass above convention. It mean if endpoint is defined with "endpointPath", then the endpoint url will be value of "endpointPath". For example:
/module_name/restEndpoints/p1/p2/p3/def_v1.yaml {endpointPath: a/b/c/v1} -> {context}

/.rest/a/b/c/v1

Comment by Mikaël Geljić [ 17/Jan/18 ]

Where does tours/v1 come from in your examples?

There's no "endpoint-prefix" anymore, as the workspace-parameters get flattened into the v2 JcrDeliveryEndpointDefinition.
For version I also leave it in users' hand to choose their strategy (with or without version tag), So:

File path (under /restEndpoints) Endpoint path  
/delivery.yaml /.rest/delivery would potentially conflict if a v1 endpoint is still configured?
/foobar.yaml /.rest/foobar you're correct re: manual web access config
/delivery/tours.yaml /.rest/delivery/tours  
/stories/v3.yaml /.rest/stories/v3 example 3rd revision of a user's endpoint config (1)
/stories_v3.yaml /.rest/stories/v3 alternative supported syntax to keep a meaningful file name (2)
/delivery/stories_v3.yaml /.rest/delivery/stories/v3 etc.

(1) changes of config change the behavior, so the version in the file name becomes a mere recommendation
(2) we wanted to support a dot instead of underscore; this needs to be supported in partial decoration first

Comment by Christopher Zimmermann [ 17/Jan/18 ]

Looks good on first impression!
How will a v2 "/delivery/tours.yaml" conflict/interact in these situations...
A. A v1 delivery endpoint is configured, that does not have the "tours" prefix configured?
B. Same as A but it does have a "tours" prefix configured?

So the version path segment is actually completely optional and does nothing special except route to a specific endpoint config?

Comment by Mikaël Geljić [ 18/Jan/18 ]

I just mentioned conflict on the first example, as it would pbly be a bad idea to name the new endpoint just delivery; or more generally to have overlap between endpoint paths on different depth (e.g. /foo and /foo/bar).
Although the request matching is usually smart enough, you can imagine ambiguity respectively between getting the bar node from the foo endpoint, and querying the bar endpoint). Nevermind, shouldn't be too common.

Re: A/B cases, you mean if you had a v1 previously configured? There's no prefix in v2; but if you mean v1 these might be good cases to check during QA.

So the version path segment is actually completely optional and does nothing special except route to a specific endpoint config?

Exactly.

Comment by Dai Ha [ 18/Jan/18 ]

Just try out the ambiguous case:
1/ add a v1 delivery endpoint with website workspace configured -> http://localhost:8080/.rest/delivery/website/v1
2/ add a new delivery endpoint with path /delivery.yaml -> http://localhost:8080/.rest/delivery/

Verified both endpoints work.

I am thinking about a mechanism to prevent conflict on paths in case a new endpoint registering.

Generated at Mon Feb 12 06:57:08 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.