Allow Customizable API Route Prefix for Improved Integration Flexibility

[genedna]

Currently, ZTM's API routes are defined directly from the root path (e.g., /api/status, /api/endpoints). This works well when ZTM is used as a standalone application. However, it can lead to route conflicts when integrating ZTM into other applications that might have their API endpoints.

Could you introduce a configuration option to set a custom prefix for all ZTM API routes? This prefix would be prepended to all existing routes.

Example:

If the prefix is set to /ztm, the routes would become:

/ztm/api/status
/ztm/api/endpoints
...

1. Seamless Integration: ZTM can be easily embedded into other applications without risking route collisions.
2. Customization: Users can choose a prefix that aligns with their existing application's structure.
3. Flexibility: This change would not break existing setups where ZTM is used standalone (the prefix could default to an empty string).

[pajama-coder]

Could you please elaborate your scenario a bit further in detail about 2 points:

1. Is it only the agent API that you're going to integrate into other apps? Or do you wish to also integrate the builtin GUI by using a separate base path for all the ztm frontend webpages?
2. How are you going to integrate it? I'm assuming a proxy in front of both ztm and other apps forwarding/redirecting requests based on paths. Is that correct?

[genedna]

Hi @pajama-coder ,

Here's some more detail about our integration scenario:

1. Integration Method: We're planning to embed ZTM directly into our Rust application by packaging Pipy as a Rust crate rather than running ZTM as a separate process.

2. API Prefixing: Instead of a global prefix, we'll dynamically assign a specific API segment to ZTM when it starts up. This would replace the default API routes. For example, ZTM's /api/status might become /api/v1/ztm/api/status.

3. Additional Integration: We're also integrating RustyVault into our application to replace ZTM's ca module.

This approach gives us much flexibility in managing ZTM's API routes within our application's overall API structure.

[pajama-coder]

OK, so my understanding to this point is:

1. You won't integrate the builtin frontend pages of ztm agent
2. You are also looking to provide a compatible ztm-ca service by using RustyVault

There's no issues to that.

As to the integration method, I'm still confused about the motive for needing a path prefix. Since the listening port where ztm agent accepts requests is controlled all by ztm, there's no way to add in other APIs into the same port, so why is a path prefix needed here? My understanding is, if you have an out-facing API that combines ztm API with other apps, the only feasible way is to put a proxy in front of both APIs, listen on a different port and forward requests to either parties behind based on paths. As you foward requests to ztm-agent, you can do path converting however you like. That's why I don't quite get the need of a path prefix.

[xiaods]

@pajama-coder please read above environment carefully:

@genedna said: "Integration Method: We're planning to embed ZTM directly into our Rust application by packaging Pipy as a Rust crate rather than running ZTM as a separate process."

I'm not sure how he managed to embed C code within Rust and have all the processes bind to a single port, it's quite amazing. If there's only one network port, then this API indeed needs to have a suffix added.

[pajama-coder]

@xiaods It really doesn't matter how you package ztm with your app. What really matters here is how you wish ztm to be called.

If you only call ztm from your app, whether in-process or inter-process, the interface won't be mistaken, thus, there's no point in renaming the API paths.

The motive for a set of different API paths only makes sense when you plan to expose to the users a combined API including both ztm API and your own API, in which case you'll have to put a proxy in front of the two and let it forward requests based on path prefixes. This way, as the proxy does the forwarding, paths can be mapped to ztm API paths for ztm requests. So again, there's no point for ztm in supporting a different base path.

[xiaods]

It really doesn't matter how you package ztm with your app. What really matters here is how you wish ztm to be called.

If you only call ztm from your app, whether in-process or inter-process, the interface won't be mistaken, thus, there's no point in renaming the API paths.

The motive for a set of different API paths only makes sense when you plan to expose to the users a combined API including both ztm API and your own API, in which case you'll have to put a proxy in front of the two and let it forward requests based on path prefixes. This way, as the proxy does the forwarding, paths can be mapped to ztm API paths for ztm requests. So again, there's no point for ztm in supporting a different base path.

I fully concur with your design approach; the crux of the issue lies in the misalignment of implementation strategies.

[pajama-coder]

@xiaods When ztm works like a lib or crate, it should go via a normal function call interface instead of HTTP, so 'base path' does make sense in that case. That is what I'm confused about.

[xiaods]

@xiaods When ztm works like a lib or crate, it should go via a normal function call interface instead of HTTP, so 'base path' does make sense in that case. That is what I'm confused about.

You found the answer, and I agree.