URI Pattern Inside and Outside of API ML

[dkelosky]

Copied from: zowe/sample-spring-boot-api-service#66

If we follow this:

   routes:
        - gatewayUrl: api/v1
          serviceUrl: /api/v1

We may have an endpoint outside of the API ML that is: /api/v1/status.

Through the API ML we would then have /api/v1/servicename/status

A concern is that this might make it difficult to be a client for both cases. Is that valid or is this normal in an API ML?

[taban03]

Hello Dan,
I also think it would make sense to have this change in the format. As Petr said we need to identify all the possible implications. I've shortly notified it to the team and we will plan a meeting for discussing it more in detail.
Thanks!

[plavjanik]

We have talked about it with Jiri Andrys from Db2 Tools.

Most of the API services use following URI pattern:

https://{host}:{port}/{contextPath}/api/v{majorVersion}/{resource}

For example:

https://ca31:1234/dbm/api/v1/pdt/something

The current API gateway URL format has a different order of the compoments:

https://{gatewayHost}:{port}/api/v{majorVersion}/{serviceId}/{resource}

For example:

https://ca3x:10010/dbmsrv/api/v1/pdt/something

It has the following disadvantages for him:

1. The API clients need to change a large portion of the URL when they access the APIs including api/v1 that is at a different place
2. The developers need to define routes like:

   routes:
        - gatewayUrl: api/v1
          serviceUrl: /dbm/api/v1

Proposal

The proposal is to allow basic routing that would map:

https://{gatewayHost}:{port}/{serviceId}/{resource}

to:

https://{host}:{port}/{contextPath}/{resource}

where https://{host}:{port}/{contextPath} is the same as the homePageUrl provided by the service or can overriden by additional APIML metadata attribute (named for example serviceUrl) if the homePageUrl is already defined to point to something else.

This would make the APIML routing the same as the default Zuul routing.

How to introduce this change

Removing existing routing can be difficult. But it makes sense to add this new routing and use it together with existing routing.

Steps:

1. Enable proposed Zuul routing without disabling the existing one
2. Update API ML documentation to prefer the new Zuul routing
3. Update guidance for new services to not specify routes in case that their URL pattern is the same as https://{host}:{port}/{contextPath}/api/v{majorVersion}/{resource} and use just homePageUrl
4. Update API Catalog to use the new format in the final Swagger document and in the UI (e.g.the base URL, Try it out, etc.) and JSON transformation in API Gateway
5. Add option to gradually disable current APIML routing in two modes - "warning" mode that will keep working but will print warning messages and remember services that are still using it, and "off" mode where it will not be working
6. Make sure that Zowe services are not using it
7. When no other services are using it then switch the old routing off by default

[plavjanik]

@JirkaAichler @pinpan @dkelosky @petr-galik Jiri Andrys have approached me to share his pains with the current routing and we have brainstormed what would be helpful for him. It seems that it possible to help him and use a better URL format without need to change the whole Zowe at the same time.

[plavjanik]

This document defines some term about URLs - https://github.com/zowe/api-layer/wiki/Components-of-URL

[plavjanik]

This document describes existing routing and some older proposal for different routing types: https://github.com/zowe/api-layer/wiki/API-Gateway-Routing

[dkelosky]

Looks great to me!

[plavjanik]

@pinpan

[dkelosky]

Hi - The links no longer work. Where has the wiki moved? Can there be links to the old locations to the new locations?

[balhar-jakub]

@dkelosky Hi - the wiki link was removed as the information there were outdated.
At the moment there are information related to the API path here: https://docs.zowe.org/stable/extend/extend-apiml/onboard-plain-java-enabler.html#api-info

We are also discussing how exactly we will go forward with respect to the API paths and afterwards we will document the results in the Zowe docs.

[dkelosky]

Thank @balhar-jakub. I'm looking for a diagram that laid out Components of a URI that @plavjanik put together. I don't know if that would still be outdated.

Perhaps in the future there can be some redirect or notice that old locations are now pointing to new ones. If these links are set elsewhere, they point to dead-ends without a clear path to finding the new location.

[balhar-jakub]

The components of the URI with respect to the Conformance criteria is outlined here:
https://github.com/openmainframeproject/foundation/blob/master/zowe_conformance/test_evaluation_guide.md
Is there any information missing?
If yes there is an issue focused on improvement of this documentation here: #646

As for the position of the service Id in the URL we are discussing the possibility to move it in the first place. The document outlining the possible solutions to this and their risks will be shared with the community once we have well written and understandable version.

[dkelosky]

Hi @balhar-jakub - yes I still do not see the components of a URL. @plavjanik had a pretty cool diagram which described things like contextPath, serviceID, and uri I think? It was a great quick visual to make sure everyone was speaking the same terms.

[plavjanik]

Hello @dkelosky, the GitHub wiki is also using a git repository. I have restored the referred pages. I have added a note to them to explain that they might be outdated and in case of the API Gateway Routing talking about possibilities so the users need to go to Zowe Docs for the current information.

• https://github.com/zowe/api-layer/wiki/Components-of-URL
• https://github.com/zowe/api-layer/wiki/API-Gateway-Routing

[jalel01]

@balhar-jakub @janan07 maybe we should rescue the visual that Dan refers to and make sure its included in the relevant places in our existing Doc?

[balhar-jakub]

@jalel01 Totally agree. I think that we should also go through these two pages and probably bring a bit more of it into Zowe docs.

[dkelosky]

Thank you all! I've come to rely on the diagram when talking to new teams; it's incredibly helpful 😄

[balhar-jakub]

There is a new proposal for the way forward with respect to the API Path Patterns capturing potential ways forward and selected way forward based on the Architecture call.

https://docs.google.com/document/d/1eCb8q9MBIktYS5-Lxysy6OcibtovZKqtnjZI19fOf3w/edit

[balhar-jakub]

The implementation of the proposed changes was moved to a new separate issue: #688
We can also continue in the further discussion there.

As such I am closing this issue as there is nothing more to be done here.