[MGNLRESTCL-91] Cannot target a path with no operationId defined in an OpenAPI v3 schema Created: 30/Oct/19  Updated: 16/Apr/20  Resolved: 13/Nov/19

Status: Closed
Project: REST Client
Component/s: None
Affects Version/s: None
Fix Version/s: 2.0

Type: Bug Priority: Neutral
Reporter: Martin Drápela Assignee: Jorge Franco
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: 0d
Time Spent: 7.5h
Original Estimate: Not Specified

Attachments: PNG File image-2019-10-30-09-19-34-775.png    
Issue Links:
Problem/Incident
is caused by MGNLRESTCL-88 DOC: Page with REST v2 configuration ... Closed
dependency
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)
Bug DoR:
[ ]* Steps to reproduce, expected, and actual results filled
[ ]* Affected version filled
Date of First Response:
Epic Link: Declarative REST clients
Sprint: Declarative REST 10
Story Points: 5

 Description   

When creating a simple example to showcase an OpenAPI v3 rest call, I've found no way to retrieve data for just an endpoint path. See this spec:

         "/action/status_show": {
            "get": {
                "summary": "Get the site status",
                "description": "Returns the site status",
                "tags": [
                    "action"
                ],
                "responses": {
                    "200": {
                        "description": "Returns the site status, version, installed extensions"
                    }
                }
            }
        },

The full OpenAPI v3 schema url is:

https://raw.githubusercontent.com/bcgov/api-specs/master/bcdc/bcdc.json

I think it should be possible with some placeholder for "/action/status_show" in the FTL:

#assign bcResponse = restfn.call("bcdc", "/action/status_show")

but currently we use something like OperationId to reference the :

https://git.magnolia-cms.com/projects/MODULES/repos/rest-client/browse/magnolia-rest-client/src/main/java/info/magnolia/openapi/client/factory/OpenApiClientFactory.java#128

which is not defined in the bcdc example schema.



 Comments   
Comment by Quach Hao Thien [ 30/Oct/19 ]

operationId is recommended as uniqued among the restEndpoint, but also be optional. If operationId is absent, path name should be set as alternative.

Note: only apply for the case path has only one method, if path has more than one method and operationId are missing to distinguish each others, could lead to out of expectation rest call. 

Comment by Dai Ha [ 31/Oct/19 ]

OperationId is optional so we have to find a way to deal with its absence, especially for remote schema files which is not possible to be edited. Missing operationalId will create no-name restCall which is not callable and OpenAPI schema is shown on Definition App as a single URL to the resource thus user can not see the name of the restCall in this case.

Here are workarounds/solutions at different levels that I can suggest:

  1. Quick one: If operationId is missing -> append path + restCall method as operationId and as restCallName, this way user can guess the name of restCall that they need to trigger.
  2. Consume the OpenAPI during yaml registration? In case of missing operationId, we can use ```info.magnolia.jcr.util.NodeNameHelper``` to assign restCall's name. But then new question is how do we refresh the schema when there is modification since we don't watch for schema file modifications, further more, it is impossible to watch remote schema file.
  3. We track schema md5 and have a timer/schedule task to scan for md5 changes periodically. New flag in definition will tell that timer/schedule task which definition to scan.
Comment by Christopher Zimmermann [ 06/Nov/19 ]

I prefer the automatic “action+path” approach. I would add a colon for readability - so “get:/action/status_show”.
I prefer this because its a “convention over configuration” approach. A developer typically has to view the OpenAPI schema or its documentation anyway. Adding the aliases would just be another place they would have to look to understand how to make the calls. With this approach developer just has one source of truth. Also it means that the OpenAPI endpoint is quicker to setup - I dont need to create any additional configuraton.

Comment by Quach Hao Thien [ 13/Nov/19 ]

For QA:

By default, restCall name will be mapped to this pattern: "method:/path/pathAction" and operationId will be considered as alias for this restCall if exists
E.g.:

paths:
  /pet/findByStatus:
    get:
      operationId: findByStatus

The path above could be invoked by either

restfn.invoke("get:/pet/findByStatus", "available")

or

restfn.invoke("findByStatus", "available")
Comment by Martin Drápela [ 13/Nov/19 ]

Added to documentation:
https://documentation.magnolia-cms.com/display/DOCS62/restfn#restfn-TheformoftherestCallName

Comment by Dai Ha [ 18/Nov/19 ]

Verified with latest CE and rest-client at master. Now user can access to OpenApiRestCall with new rest client name or with operationId (if it is defined)

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