search

mulesoft / api-console

An interactive REST console based on RAML/OAS files
Other
910 stars 237 forks source link

Add an option to disable URL encoding #553

Open ibnesayeed opened 6 years ago

ibnesayeed commented 6 years ago

While this is generally a good idea to URL-encode path and query parameters, there can be places where an enforced encoding might come in the way. For example a service might expose and endpoint /screenshot/{URL} where the server might allow users to specify a plain URL in the path as the last element without any encoding for better readability and easier manual interaction. The service might happily accept anything like /screenshot/http://www.example.com/foo.bar?baz=blah&lorem=ipsum and treats everything after the /screenshot/ as a single parameter.

While this may not sound like a good practice, it has been very commonly used in services where a URL is the primary identifier or parameter for the service. Some examples include web archives (including biggest of them all, the Internet Archive), browser emulators for testing, URL shortners, URL bookmarking services and whatnot.

Currently, the Try It implementation URL-encodes any such parameters. It would be nice to have a config option to disable this behavior.

jarrodek commented 6 years ago

When you are using query parameters panel to update params values they are automatically URL encoded. However if you use URL editor to put the same value it won't be encoded.

I am not planning to add any UI controls to enable / disable auto encoding because we don't want to make the UI busier than it's required. Since there's a way to send unencoded string I am closing this issue as wont fix. However I am open for discussion.

ibnesayeed commented 6 years ago

I am not planning to add any UI controls to enable / disable auto encoding because we don't want to make the UI busier than it's required.

I am totally in favor of not adding a UI control, because it is not something I would want the end user to decide (and get confused). Instead, if we can do something about it in the form of decorating certain fields in the RAML file using comments or as a config option to disable this behavior globally or in selected fields, it would be great.

jarrodek commented 6 years ago

OK, that makes sense. RAML has annotations that the console can read to to make appropriate changes. I was planning to introduce few global annotations that can be used to control console's behavior. I would need to find my old notes to the console. However, the problem is that such annotations could be used only for the console which makes it not scalable. I will consult other teams if any other Mulesoft product uses annotations and maybe we could present a list of some global annotations supported by all our products. Also the console could support configuration option for disabling / enabling auto encoding. It would only make sense if the console is used as a HTML element so you can control conditions for this options.

I am reopening this and will investigate further in about a week.

BTW, I am hoping we are discussing v4?

ibnesayeed commented 6 years ago

BTW, I am hoping we are discussing v4?

As long as it arrives eventually (but not too late), the version is the last thing I would worry about.

While a configuration option in the form of annotation or decoration may come later, what would be good if the generated HTML custom element introduces a property to disable it earlier, independent of the next RAML spec version (which can be set later using YAML annotations). This way, we can manually make those changes for now in the generated markup to get our documentation working for now.