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": "testuser@gmail.com",
        "name": "Johny Tester"
    }
]

### Create a user

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

{
    "email": "another@example.com",
    "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": "testuser@gmail.com",
#        "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 :)

[pyrossh]

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": "testuser@gmail.com",
        "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

[justintime4tea]

Question

I understand you've (@Huachao) considered "export feature" as out of scope to whatever degree but with that said, has any progress from anyone been made on "export to OpenAPI, HAR, etc..." support and/or tooling?

I think the .http/.rest file format and "HTTP Language" have the opportunity of becoming a minimalist "markdown styled" approach to describing and executing API calls in editors and the CLI.

RANT

I can't stand these mammoth sized API clients like Postman. They are a HOT GUI mess (see what I did there?). I've gotten by with Insomnia for a while (much more elegant design than Postman, minimalist approach, almost distraction-less) but this HTTP format and "language" are far superior IMO.

Problem

Other formats (HAR, OpenAPI, etc...) are not very "human readable" (IMO). They are full of distractions (along with the GUI's that support them).

Solution ?

I feel that the "HTTP Language" here provides an API documentation solution in the same "vein/style" to what Markdown provides for documentation. Where Markdown is an alternative to HTML, DOCX, ODF, or other "style and structure" languages/formats the "HTTP Language" could become a great alternative to HAR, OpenAPI/Swagger, WSDL, etc...

Call to action?

I feel strongly that there is a need in our domain for a minimalist and human readable file format and spec for documenting and executing HTTP (GraphQL, gRPC, etc...) calls; this project, file format, and language are a great start!

Who wants to collaborate on this? Please, message me! [ HTTPLang (at) jgross (dot) tech ]

For those of you working at companies that use this (and that contribute to OSS), could we persuade our companies to contribute to a spec like this?