option to specify basepath in prism mock server

[esoni88]

User story.
Hi all,
in my yaml i ve specified
servers:

• url: https://localhost:3000/poll-maker/v1

so if exist a path /hello i want that mock server respond to
https://localhost:3000/poll-maker/v1/hello

how can specify basepath poll-maker/v1 in mock server ?

[XVincentX]

Hey @dario-frongillo,

Prism non supporta nessun basePath, né per OpenAPI 2 né per OpenAPI 3.0, qui trovi le nostre motivazioni a riguardo.

Scrivici ancora se hai bisogno di chiarimenti a riguardo.

[mullerch]

Still this feature would be useful so that the mock server corresponds as much as possible to the production infrastructure.

This could be done with a CLI option:
--basepath, -b

Usage: prism -b /poll-maker/v1

[ynarwal]

I agree with @mullerch here it's really handy to have this feature available @XVincentX are you open to a PR ?

[XVincentX]

As mentioned here — we are not going to support such feature.

[boeboe]

@XVincentX ... the argument not to support this does not make sense to me. Basepath and server are both essential elements in the V2 and V3 specification. Not supporting it because "it is confusing to some others" does not make sense. It is very little implementation work to implement this and you can still keep the default behavior to ignore it, if you wish (although I do not understand why a client implementation would need to make an exception w.r.t basepath just because a mock server is not implementing it correctly). The only way to support a real mock server now (and having the right full URL paths is essential for that), is to front prism with a reverse proxy to do URL remapping.

I am going to need to look for alternatives, as the goal of a mock server is to stay as close to the specifications as possible, not to make exceptions and chose to ignore essential elements. Clients, like SwaggerUI and others, all are implemented taking the basepath or server correctly into account.

https://microcks.io looks very promising.

[XVincentX]

Hey @boeboe,

I'd be interested in learning more about how the lack of basePath support is preventing you from completing your work.

I'm open to new ideas and — in case there's a convincing argument, we can reconsider.

[philsturgeon]

@boeboe Conceptually, Prism starts where your API starts, and the preceding gumph to get to that point is irrelevant.

Your API starts at https://localhost:3000/poll-maker/v1, that is the Server URL of the v1 API that is described in your OpenAPI file.

Prism runs an alternative server on another equivilent server URL. You can swap out either server URL and they will "stay as close to the specifications as possible", and $SERVER_URL/hello will be the same.

If you could explain the actual problem you're having I could perhaps help further, but so far I am not sure if there is a problem?

[hpatoio]

Here my setup. Dunno if it can help

My OpenAPI has:

    {
      "url": "https://api.foo.localhost/api/v3",
      "description": "Dev server"
    }

and an endpoint like

    "/cities/{cityId}": {
      "get": {

I call my application directly using https://api.foo.localhost/api/v3/cities/milan and everything works.

I then start Prism with

proxy -p 4010 --host 0.0.0.0 /srv/openapi-3.4.0.json http://api.foo.localhost/

If I call:

https://localhost:4010/api/v3/cities/milan

I get

core.prism       | [10:14:16 AM] › [HTTP SERVER] get /api/v3/cities/1 ℹ  info      Request received
core.prism       | [10:14:16 AM] ›     [PROXY] ℹ  info      Forwarding "get" request to http://api.foo.localhost/api/v3/cities/milan...
core.prism       | [10:14:18 AM] ›     [PROXY] ℹ  info      The upstream call to /api/v3/cities/milan has returned 200
core.prism       | [10:14:18 AM] ›     [VALIDATOR] ⚠  warning   Violation: request Selected route not found

If I start Prism using (please note api/v3 at the end)

proxy -p 4010 --host 0.0.0.0 /srv/openapi-3.4.0.json http://api.foo.localhost/api/v3

no warning is returned

[philsturgeon]

Your API lives at https://api.foo.localhost/api/v3 in development, and the mock API lives at https://localhost:4010/. These two URLs are equivalent, so there is not much point in mixing them in together.

Is there a tangible benefit from taking some of the server.url and appending it to the mock URL?

https://api.foo.localhost/api/v3/cities/1
---------- server -------------|- path -


https://localhost:4010/cities/1
----- server ---------|- path -

This keeps is clear and seperate The only thing you need to interact with is the paths that are part of your API, and that means /cities/1 not /api/v3/cities/1 as that's got some of the server and some of the path kinda smushed together.

[hpatoio]

I agree with what you said. The fact is that this setup does not work (maybe I'm doing something wrong)

OpenAPI

    {
      "url": "https://api.foo.localhost/api/v3",
      "description": "Dev server"
    }

Prism started with

proxy -p 4010 --host 0.0.0.0 /srv/openapi-3.4.0.json http://api.foo.localhost/

cURL

curl --location --request GET 'localhost:4010/cities/1'

I get in the logs (no /api/v3/ in the log)

core.prism       | [1:18:38 PM] › [HTTP SERVER] get /cities/1 ℹ  info      Request received
core.prism       | [1:18:38 PM] ›     [PROXY] ℹ  info      Forwarding "get" request to http://api.foo.localhost/cities/1...

While, AFAIU, it should be Forwarding "get" request to http://api.foo.localhost/api/v3/cities/1...

If I start Prism in this way (please note '/api/v3/` at the end)

proxy -p 4010 --host 0.0.0.0 /srv/openapi-3.4.0.json http://api.foo.localhost/api/v3/

then everything works

core.prism       | [1:22:50 PM] ›     [PROXY] ℹ  info      Forwarding "get" request to http://api.foo.localhost/api/v3/cities/1...

So am I missing something and I'm doing something wrong or url is not considered ?

[philsturgeon]

Because your server URL is https://api.foo.localhost/api/v3 you would want to pass that in as the upstream server URL:

proxy -p 4010 --host 0.0.0.0 /srv/openapi-3.4.0.json https://api.foo.localhost/api/v3

[hpatoio]

Sure. What I wanted to say is that the part in the FAQ that talks about server.url is IMHO misleading. Because that value is not read/used by Prims. I'll try to open a MR

[philsturgeon]

Ahh I see what you mean. That FAQ is talking about mocking only, it was written before the proxy existed. If you could take a swing at wording there I'd appreciate it, otherwise I'll fix it up.

[sspieker-cc]

Perhaps a different use case may help to explain the request to support such a feature request. Firstly, if this feature request is "optional" meaning that we are simply adding to existing behaviors, then we have not created a regression and documentation requested above can help to outline the usage of this additional feature.

The use case that I am describing here is one focused on a large and complex series of services that have interdependencies and configured from external sources. So, for example, Service A starts and receives configuration information from another service found within the DEV environment. Some of these configs are pointing to endpoints in Service B which we will continue with the paths defined above 'localhost:8080/api/v3/cities/1'.

Now we would like to use the Prizm mock server to emulate Service B without having to manipulate configurations for testing. We would suddenly have a host that is now only able to respond to: 'localhost:8080/cities/1' which now "breaks" the pathing to the endpoint and configurations are also incorrect based on the limitation placed on us by Prizm simply because we cannot inject that component into the path that Prizm will respond to.

The behavior is a behavior of deploying a Java WAR file to an EE container such as Tomcat. The basePath of the application will match the name of the WAR file and all endpoints will be relative to this name.

We are looking to perform A-B-C type testing with all other dependencies being mocked through Prizm as a simple plug-n-play solution. If we cannot get Prizm to respond on such path references then we will not be able to utilize this tool (which is amazing BTW).

Is this use case making more sense as to the importance of the BasePath feature request and how important that can be for very complex infrastructures that cannot easily adapt to suddenly changing API endpoint references?

Thanks,
Scott

[serefarikan]

Hi @sspieker-cc I came here looking for the feature requested in this issue, but I got nerd sniped by your description :) Just for the purposes of intellectual curiosity, can you explain a bit more why you're not able to update the service that provides endpoint for service B? In your examples, you're using localhost so in staging/prod etc you must be updating these "endpoint" configuration values anyway? I'm just trying to understand what the bottleneck is. I do agree that having this feature would be nice, without having to resort to nginx etc. Though the use of proxy discussed in this thread seems to do the trick.

[imkarrer]

As mentioned here — we are not going to support such feature.

Hey @XVincentX I was wondering if stoplights stance has changed on this topic over time. I have one question followed by our use case.

Why cant prism detect an OAS2 spec and construct the full path according to OAS2 semantics?

We have a bunch of wiremocks I am replacing in our integration test environment. So far all have been OAS3 specs. I have replaced all but one which is a OAS2 api with a basePath in its spec. Therefore the existing wiremock includes the expected basePath in the mock URL.

I cannot swap out the wiremock for a prism mock without changing the OAS2 spec and everything else in this service that assumes basePath is available or adding plumbing to configure the dependent services to not insert the basePath when started in the integration test env to align with Prism.

Im going to try and find a way around this because we love prism, but this is a pretty rough edge for folks dealing with legacy services, and means prism doesn't fully support OAS2 which is implied in the preamble of the README.md.

Edit: maybe I put nginx in front of the prism mock to insert the basePath....not sure if that will work or not with out reading some docs. proxy_pass option looks promising. If this works out happy to add a docs update to socialize the work around.

Edit Edit: nginx + proxy_pass works for me. Happy to submit a docs update if I get to put an asterisk next to OAS2 support for the next person who will need this.

[XVincentX]

@imkarrer I have left Stoplight more than two years ago; I believe @chohmann is the best person to talk about this feature request.

A proxy, such as Caddy or NGINX would be able to give what you want, so that is a route you might want to pursue.

[imkarrer]

Thanks for the snappy redirect! Cheers!

[imkarrer]

we ended up pivoting and exposing a variable to configure the upstream services to also not use a base path 🤷 in the test env. proxy solution is way too clunky.

[jasonm23]

So this needs to get revived.

If anyone has a PR for adding the option --basepath '/v1/ etc, please let me know.

The "use NGINX" response is bizarre, frankly.

[gavenkoa]

The "use NGINX" response is bizarre, frankly.

We use prism for mocking from OpenAPI spec. And Spring Swagger generates YAML spec without context path. The apps, consuming mock server, we need to reconfigure to strip basePath or to edit every entry in YAML spec...

[jasonm23]

@gavenkoa - Using the NGINX workaround will get you rewritten URLs easier than those methods, but the point is adding a --basepath option to the prism cli, get's the job done far easier.

General note:

The reason why I say the NGINX suggestion from (admittedly former) a project dev is bizarre, is that the supposed rationale (in the source code/readme) for not implementing --basepath option is because it'd be confusing. Is this just extreme pessimism? Honestly I don't know who'd be confused:

By not using the option the user would get the urls without a base path prefix and would not trouble them at all. It'd be default behaviour, breaks nothing, etc. etc.

Providing the option, however is good value to users who have to deal with this issue, and do not want or need another layer (nginx) to discuss/socialize in development docs etc.

[kmatthews812]

+1 to the fact that this is baffling.

From the FAQ, "a request to http://localhost:4010/hello would work, but http://localhost:4010/api/v1/hello will fail"

So there is no way to make http://localhost:4010/api/v1/hello return without editing the "paths" section of the OpenApi spec (causes code generation issues elsewhere) or running a proxy (clunky and difficult to roll out across a non technical team)?

This almost makes this project unusable, which is a shame for such a strong project otherwise.

[imkarrer]

We were able to startup the service under test and point it to mocks without a base path by exposing a configuration for the service under test. This way we did not have to massage the mocks to include the base path, we consume them as is.

I am still 100% with you, but it was not the worst trade off in the world to configure the service to hit the URL without the base path in our integration testing environment. Its also something you might want to be configurable anyways. The down side is you need separate configs to set the URL for local dev / promotion environments.

[imkarrer]

Actually, the biggest trade off is communicating to my peers why we have to do this, and linking them to this thread :)