Bru Lang: New Syntax Proposal for storing requests

[helloanoop]

Proposed Syntax - right
Current Syntax - left

[pove]

Thank you to ask to the community these important decisions.
I just want to point that the comparison should be done with complete/complex examples. How body, scripts, assertions, etc, will show? How these changes are improving readability? It will be easier to edit .bru files? It will affect changes review in commits?

Sorry for so much questions...

[rabestro]

It would be helpful to understand the reasons for switching to a new file format.
What problems exist with the old format?
What are the advantages of the new format?

Currently, many companies are dealing with the challenge of switching from Postman to another tool. If the syntax and format of the language change with each version of Bruno, it creates significant risks and uncertainties. This situation makes many companies hesitant to consider Bruno as a viable alternative to Postman.

[rabestro]

I am not sure why it was not feasible to use the YAML format. This format is commonly used in various areas, including describing the Open API specification. Apart from being human-readable, many libraries can read this format for different programming languages. When we create our own language, we face a situation where there are no libraries that can read it.

[rabestro]

As an experiment, I asked artificial intelligence to try to represent one of the HTTP queries using the YAML.

The original Bruno file:

meta {
  name: Translate sentence to Pig Latin
  type: http
  seq: 1
}

post {
  url: {{host}}/pig-latin
  body: json
  auth: none
}

headers {
  Content-Type: application/json
  Accept: application/json
}

body:json {
  {
    "sentence": "Hello, World!"
  }
}

assert {
  res.status: eq 200
  res.body: isJson
  res.body.sentence: isDefined
  res.body.sentence: isString
  res.body.sentence: eq "ellohay, orldway!"
}

docs {
  Translate English sentence to Pig Latin
}

The prompt: Let's assume you need to represent this data in YAML format. How can you do this?

The response:

meta:
  name: Translate sentence to Pig Latin
  type: http
  seq: 1

post:
  url: "{{host}}/pig-latin"
  body: json
  auth: none

headers:
  Content-Type: application/json
  Accept: application/json

body:json:
  sentence: "Hello, World!"

assert:
  res.status: eq 200
  res.body: isJson
  res.body.sentence: 
    - isDefined
    - isString
    - eq "ellohay, orldway!"

docs:
  - Translate English sentence to Pig Latin

[helloanoop]

Hi @rabestro

Today, we support Bru lang. Support for using yaml / toml while parsing the lang are on the roadmap

Why Bru ?

As one of the advantages of Bruno is that the entire collection is able to be treated as a git repository, having contextually standard key order as well as a relatively compact textual representation is a huge benefit, and that's something that the "big 3" formats (json, yaml, toml) cannot viably provide, but a custom language as is already used can. - @halostatue

Below I am picking an example to explain these nuances

In Bruno UI, you can save duplicate key val pairs. Ex: below use case is perfectly valid

We also need to store whether the value is disabled or not.
And we will support storing descriptions in the future (for all keyval pairs in Bruno like headers, params, vars ...)

So in bru it would be like

http:
  params: {
    query: {
      userId: 1
      userId: 2

      @description('whether the user is active or not')
      status: active

      @disabled
      page: 1
    }
  }

Where as in yaml it would be like.

http:
  params:
    query:
      - 
        key: userId
        value: 1
      -
        key: userId
        value: 2
      -
        key: status
        value: active
        description: whether the user is active or not
      -
        key: page
        value: 1
        disabled: true

Lets take another example with headers

http: {
  headers: {
    Content-Type: application/json
    Authorization: 'Bearer: {{token}}'
    Accept-Encoding: gzip, deflate, br
    Accept-Language: en-US,en;q=0.9
    User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)
  }
}

Same thing in yaml

http:
  headers:
    -
      key: Content-Type
      value: application/json
    -
      key: Authorization
      value: 'Bearer: {{token}}'
    -
      key: Accept-Encoding
      value: gzip, deflate, br
    -
      key: Accept-Language
      value: en-US,en;q=0.9
    -
      key: User-Agent
      value: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)

[helloanoop]

@rabestro Just quoting another example to highlight the examples of a markup language that supports annotations and multimaps

I am sure you agree that large openapi specs are not a pleasure to hand code and work with.
Here is a comparison of how it would like in Bru

OpenAPI Yaml

openapi: 3.0.0
info:
  title: Todo API
  version: 1.0.0
paths:
  /todos:
    get:
      summary: Retrieve all Todos
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                todos:
                  - id: 1
                    title: "Complete assignment"
                    completed: false
                  - id: 2
                    title: "Buy groceries"
                    completed: true
    post:
      summary: Create a new Todo
      requestBody:
        required: true
        content:
          application/json:
            example:
              title: "New task"
              completed: false
      responses:
        '201':
          description: Todo created successfully
          content:
            application/json:
              example:
                id: 3
                title: "New task"
                completed: false

OpenAPI Bru

openapi: 3.0.0
info: {
  title: Todo API
  version: 1.0.0
}
paths: {
  '/todos': {
    @summary('Retrieve all Todos')
    get: {
      @description('Successful response')
      @status(200)
      @contentType('application/json')
      response: '''
        [{
          "id": 1,
          "title": "Complete assignment",
          "completed": false
        }, {
          "id": 2,
          "title": "Buy groceries",
          "completed": true
        }]
      '''

    @summary('Create a new Todo')
    post: {
      requestBody: '''
        {
          "title": "New task",
          "completed": false
        }
      '''
      @description('Todo created successfully')
      @status(201)
      @contentType('application/json')
      response: '''
        {
          "id": 3,
          "title": "New task",
          "completed": false
        }
      '''
    }
  }
}

[bkir]

Would this also change for GraphQL requests? If so, how? Currently, I like that the operation and vars have separate blocks in .bru files: