Add ability to define possible values for query params

[svenluijten]

For example, we support a sort query param in our API that can have the following values:

• start
• -start
• end
• -end

It would be great if I could set the "possible values" for the sort query parameter in Bruno, so I don't have to go back to the code/documentation to check what options I have.

[conejoninja]

I agree with @svenluijten one key point that keep us from migration to Bruno is that our Postman documentation/examples are lost and we don't see any way to include it in Bruno. Our clients benefit from having some sort of explanation in specific params and looking at some example responses (without the need to execute the query itself).

Did we miss something?

[helloanoop]

Did we miss something?

Currently Bruno does not have this. I really like the idea.

Here is how a rough idea of how we can fit this in Bruno's way of doing things.
Open to feedback and changing this approach.

We store a the choices in the request vars using @choice() annotation

If a choice variable gets referenced inside a query param, then we should a select dropdown in the right side of the value cell.

@ajaishankar Do you have any in inputs on the Bru Lang DSL ?

Delivery Timeline

A bit tied with some things. If we agree on the design then I don't think any Bru Lang Transpiler updates would be needed.
This should be just a UI level change.

[conejoninja]

In case of documentation/params explanation, it just need to show up as a different tab, content could be in markdown.

For example response, a json/xml would be enough in most cases, but I guess the same as before applies, just a new tab/area to show some markdown content.

Just like Postman do, this would be great not only for Bruno's UI, but for other form of representation (like a website)

[helloanoop]

Created a a seperate issue to track request docs here

Let's continue to use this thread for discussing "choice" request params.

[svenluijten]

I like the idea of a @choice() annotation to facilitate this! This would even map pretty well onto the OpenAPI spec's enum property type.

[ajaishankar]

Looks like a var needs a type 😄

In the DSL we could move the types to a separate section.

As long as we keep this minimal, the following could work...

vars:types {
  sort   : enum   start, -start, end, -end
  month  : enum   Jan=1, Feb, Mar
  img    : file   format=binary
  images : file[] format=binary
  pic    : file   format=base64
}

In the UI we can add a type column for a var.

Please see discussion on how to specify File Uploads too

[svenluijten]

Instead of introducing a new vars:types block, I'd just keep it the same as it is now, with the type inferred (handled as it currently is) if no type is specified.

vars {
  message
  ~token
  sort  : enum(start, -start, end, -end)
  img   : file(format=binary)
}

Edit: Ah wait, I think I misunderstood what you were saying @ajaishankar; you're saying the vars:types block would just define the types, not the vars themselves. Then if you would have those types from your example defined, you could use sort in any var, and it'd automatically be of that type enum. I like it!

[ajaishankar]

@svenluijten yes if we introduce a vars:types block that would define the type of a var.

If we want to keep this inline, feel it will be better for the type annotation to go on the left hand side, like the ~ in front of the token.

vars {
  message
  ~token
  @enum(start, -start, end, -end) sort :  -end
  @file(format=binary) img 
}

In the UI think we might need a new optional column to denote the type (enum, file, file[]) etc

[name] [value] [type?]

Or when hovering over the variable name a popover link could be clicked to edit the type.

[helloanoop]

@ajaishankar

Keeping TOML in mind

I would also consider our future plan to support TOML which currently seems to be a possibility
Here is what chatgpt gave me when I asked how Bru would look in TOML: https://chat.openai.com/share/f92457d3-5c9c-4025-b369-cf7dc60a9b92

I think, we can only look at that post v1 on a more serious level, but I'd have it in back of my mind.
TOML supports enclosing keys in quotes, I don't see a risk in introducing a special char at the key level

DSL

I am almost in agreement, just running scenarios in my head if this would break anywhere

vars {
  message: hello
  ~token: secret
  @disabled key: secret
  @enum(start, -start, end, -end) sort :  -end
  @file(format=binary) img 
}

PS: In the future, we can consider replacing ~ with @disabled too. Let me know what you think, I agree with the general sentiment that perhaps ~ is not as intuitive, and if we decided to support directives, why not making it common

UI

We have a lot of people (>10k) using the app now, what I am seeing is that no-one actually is too concerned about the DSL. Everyone is pretty happy that the format is human readable (and would love to use a standard). Key point I am conveying is that very few people would hand-code the request on a file. If they really wanted to do that, they likely would choose a tool which is exclusively made for handcoding (https://hurl.dev/)

I also never hand-code, I just use the UI. Our UI should hide this abstraction neatly. Instead of providing a third column, we should provide a special row that gets rendered differently if the user has chosen a special var/param/header/path. Next to "+ Add Var" will be dropdown icon, and then the user can choose "+ Add Enum", "+ Add File"

I will put some small UI over the weekend to demo this idea. The file upload - #195 is very crucial for the community and we need to get to it sooner than later

[helloanoop]

@conejoninja Happy to share that Bruno v0.24.0 supports request level documentation.