Create a standard for HTTP/REST files

[wekempf]

JetBrains have had support in their IDEs for http/rest files for years. Their implementation differs from the VSCode REST Client extension. VSCode has another extension, httpYac, that provides yet a third implementation that borrows from both of the others. Now Microsoft adds a fourth variant that's different from any of those. These are the implementations I'm aware of, but I'm sure there's others. They all get enough the same to make you think we've got something great, but then they don't get enough the same to really use this across IDEs, editors and command line. Everyone needs to stop, get together and create a standard that can exist across these tools.

Things from each that should be in such a standard.

1. Support for pulling variables out of environment files... especially a private file that won't be checked in to version control.
2. Support for variables within the http file itself.
3. Support for naming requests and defining request dependencies.
4. Support for JavaScript blocks. This means support for request, response and client objects need to be standardized.
5. Favor JavaScript over "magic". There's no need for a {{$guid}} magic variable if JavaScript can create a GUID and assign it to a variable. REST Client has a lot of magic to support things like authentication that would have been better left to JavaScript blocks.
6. Support unit tests.

Ideally we'd have both IDE/editor support and CLI support for running, but if there's a standard format then third parties can supply the CLI solutions.

[Enter feedback here]

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 26f1374f-556a-35fc-cc42-b8911746db80
• Version Independent ID: 26f1374f-556a-35fc-cc42-b8911746db80
• Content: Use .http files in Visual Studio 2022
• Content Source: aspnetcore/test/http-files.md
• Product: aspnet-core
• Technology: aspnetcore-test
• GitHub Login: @tdykstra
• Microsoft Alias: tdykstra

[tdykstra]

cc @sayedihashimi

[sayedihashimi]

FYI I updated the title to better reflect the contents of the issue.

[sayedihashimi]

I think it would be great to have a standard for this file. As I've learned more about both the VS Code REST Client extension and the Rider support, I'm seeing how different the implementation is. From the Visual Studio side, we are targeting maximum compatibility with the VS REST Client, but we would love to have good support in Rider as well.
I'm in favor of creating a standard for this file, or trying to maximize compatibility across the three different tools.

@maartenba and @Huachao what are your thoughts on increasing compatibility or defining a standard for HTTP/REST files? I've never done anything like this, so this is new territory for me.

[wekempf]

Don't forget httpYac. It aimed for more compatibility with JetBrains, but does include some features from REST Client. Of the 3, that's my preferred implementation, actually. But the core idea of leveraging JavaScript blocks for much of what REST Client does through other conventions I think is the more appropriate way to go. Nothing wrong with implementations including other features, but the core of a standard should focus more on using JS than on using conventions one must learn.

I've got a fair amount of experience with using REST Client and httpYac, and to a lesser extent the JetBrains IDEs (Pycharm rather than Rider, but all JetBrains IDEs are the same here). If you're interested I would be willing to participate in any discussions or anything else for that matter.

[sayedihashimi]

Yes httpYac looks like it's a superset of the VS REST Client and it has some really great features as well.

If you're interested I would be willing to participate in any discussions or anything else for that matter.

Ok great, if we form some "panel" of stakeholders I will certainly keep you in mind. Like I said, I've never done this before so I'm not sure exactly how this may pan out.

[wekempf]

Using the RFC to define the requests was 100% the right thing to do. When other functionality was needed to handle things like authentication, I think REST Client did the wrong thing with inventing conventions, rather than sticking with existing standards and using JavaScript blocks, which is what JetBrains did, and httpYac preferred.

[jreznot]

Everyone needs to stop, get together

This effectively adds more power to big corporations and stop innovations, I feel.

[wekempf]

Stopping innovation you could argue about, but standards remove power from corporations or any individual entity. In fact, that's precisely why something is needed here, so that we aren't in a walled garden.

[wekempf]

I'm sure this is hardly a complete set, but I've gathered together a few of the tools that would benefit from standardization here, and who's owner's might want to participate in any discussions.

vscode-restclient
httpYac
IntelliJ IDEs
dot-http
hurl
prestige
restclient.el
rest.nvim

[maartenba]

In terms of compatibility on the JetBrains side, we will start adding support for @ variables – this seems to be the most pressing to support the files that ship with the dotnet new templates.

There's a lot of functionality already in our HTTP client, including gRPC/WebSockets/GraphQL and even a way to embed (some) JavaScript to run things like test assertions (see screenshot below). There are also command-line tools to run requests and tests outside of the IDE.

As for discussions on standardization, definitely open to talking about that. For future reference, here's the syntax we support.

[wekempf]

@maartenba That's great, and definitely moves things closer. The support for JavaScript is maybe the bit missing from others. That and the need to standardize on how to define environments (different tools use different file names and even syntax, i.e. JSON files vs. .env files). There's other features I'd like to discuss in a broader standard, but these would be the biggest things to bring some compatibility between the tools. I'm glad to hear that at least two vendors are interested in compatibility, if not further discussion on a "standard".

[sayedihashimi]

That's great to hear @maartenba, it will be great to have support for the @ variables.

Once we get over that hurdle, we can work together to improve the compatibility more over time. Currently in VS we don't have support for most of the syntax that the HTTP file supports. I'll take a look at the link you provided when we are implementing features so we take those into account as well.

I think after we make some progress on the VS side we can start to identify the gaps and then get more compatible over time.

[jefflomax]

Being able to request a token and get it into "the next" endpoint you call is a great deal more important than what's mentioned here.

[keithnicholson]

Encouraging environment variables and user secret files. I cannot type in PII with the risk of it being committed.

[Rick-Anderson]

In terms of compatibility on the JetBrains side, we will start adding support for @ variables – this seems to be the most pressing to support the files that ship with the dotnet new templates.

Closing due to JetBrains.