Vscode-restclient: API Description(Request and Response) support in HTTP language

[borekb]

I'm new to this awesome extension but if I understand the HTTP language format correctly, it is only for _requests_. It would be great if I could also provide examples of _responses_ so that the .http file can be a full example for my colleagues, but executable at the same time.

For example, it would look like this:

### Get users

GET http://localhost/users

---

200 (application/json)

[
    {
        "email": "[email protected]",
        "name": "Johny Tester"
    }
]

### Create a user

POST http://localhost/users
content-type: application/json

{
    "email": "[email protected]",
    "name": "New User"
}

---

200 OK

Everything below the three dashes is just an example text, not interpreted in any way, but useful for humans reading the example.http file.

Something like that.. (I'm not saying it should be exactly this way).

[Huachao]

@borekb thanks for your suggestion, before defining a new syntax, one way to workaround to comment these response examples, so that it won't affect normal request flow, like:

### Get users

GET http://localhost/users

# Sample Response
# HTTP/1.1 200 OK
# Content-Type: application/json
#
# [
#   {
#        "email": "[email protected]",
#        "name": "Johny Tester"
#    }
# ]

### Create a user
...

But in this way you won't leverage any syntax highlight for response headers and so on. And in fact the raw response of request can be highlighted in .http file, but if doesn't meet your requirement that still executable

[borekb]

Good points.

Actually, one possibly related, even further looking idea: we currently use API Blueprint to describe our APIs and while it's relatively OK, it's not directly executable and the format is more complex than it needs to be, IMO. .http ("dothttp"?) is closer to the metal, executable and with a bit of updates, it could also be a simple Markdown-based, API description language.

It could start small: just the support for responses would be close enough for our API description needs.

Just some food for thought..

[Huachao]

@borekb good points 😄. My original goal for this extension is to let users send requests in vscode easily, so incorporate the API description in the .http file is not in my scope. I think creating a new way in my extension is not necessary, since already many tools target for this, like Swagger, RAML and API Blueprint.

So can we work in another way, my extension can import these api description files from these tools, and when you want to send request, just import them, I can convert them to .http file with no(or simple) description, and then you can send request as you wish in my extension. And my extension and API BluePrint can have separate roles

[borekb]

Sounds good!

[borekb]

We're using Rest Client more and more in our team and it sort of _is_ becoming the API description language for us, just with lots of things being inside comments. Just saying :)

[pyros2097]

I know this is not in the scope of the project. But allowing us to do this will make restclient our documentation and api tester (Thereby replacing postman/curl/swagger which I don't prefer).
If this data is in comments it will kinda be hidden.

200 (application/json)

[
    {
        "email": "[email protected]",
        "name": "Johny Tester"
    }
]

[richarddavenport]

@pyros2097 @Huachao I think ultimately what should be added is the ability to do block level comments. Current # is for line comments. I think what would solve a lot of problems is a simple block level comment delimiter.

Examples:

JavaScript

/*
The code below will change
the heading with id = "myH"
and the paragraph with id = "myP"
in my web page:
*/
document.getElementById("myH").innerHTML = "My First Page";
document.getElementById("myP").innerHTML = "My first paragraph.";

PowerShell

Copy-Item demo.msi C:\install\demo.msi #copy the installer

<#
   Running this script will make your computer catch fire!
   Last updated: 1666-09-02
#>

Get-Content -Path <#configuration file#> C:\app64.ini

Shell

#!/bin/bash
echo "Say Something"
<<COMMENT1
    your comment 1
    comment 2
    blah
COMMENT1
echo "Do something else"

#!/bin/bash
foo=bar
: '
This is a test comment
Author foo bar
Released under GNU 
'

echo "Init..."
# rest of script

Just one other side note regarding this becoming peoples documentation. If you supported markdown within these block level (multiline) comment blocks, you could effectively run these files through a markdown parser and the documentation would look fantastic!

[Huachao]

@richarddavenport great suggestion, I will consider this carefully.

[CatsMiaow]

If /** ... */ block comments are supported, can also use apiDoc, JSDoc