Editor-based Rest Client

Among other features introduced in 2017.3 EAP we mentioned the editor-based REST client, which offers a new approach to working with web APIs.

Earlier, you could run your requests with the REST client built right into PhpStorm, but it required crafting each request by hand with lots of button clicking, adding and completing of fields, and so on.

What if we wanted to leverage the power of the PhpStorm editor for the very same task, with completions, refactorings, navigation, VCS capabilities and what not? That’s where the new editor-based REST client comes in. No more fiddling with tool windows: your HTTP requests are now first-class citizens in PhpStorm.

Working with the Editor-based Rest Client

The new REST client’s interface will be instantly familiar to you, since it’s the code editor itself.

You work with HTTP requests by creating and editing the corresponding HTTP request files (using the .rest or .http extension), which are now supported by PhpStorm. If you worked with web APIs before, the HTTP format syntax will feel common and natural. It generally follows the RFC standard but includes several accommodations to better fit your developer needs.

You can start working with a web API by simply creating a new scratch file, setting its Language to HTTP request, and typing the request.

We’ll use the excellent (and free) service called httpbin to test our example requests.
Let’s start with a very simple request to https://now.httpbin.org/, which should return current time. Notice that as soon as you start typing, the completion mechanism offers completing the request scheme. Note also that you can freely omit the GET method type as it is the default.

new_scratch_file

Feel free to use completion while composing the request. Now, it supports message type (GET, POST, etc.), request scheme (http, https), HTTP request version (HTTP/1.1), header names, content types, and encodings. We plan to enhance its capabilities in the future.

As soon as you finalize the request, you can immediately run it by either clicking the Run icon in the left gutter or invoking the Run request intention action with Alt+Enter:

run_request

The request’s detailed execution results are displayed in the Run tool window:

request_results

Right after your original request in the editor, you will now see the link to the response output, which is a JSON file in our case.

request_results_link

Since this response actually gets saved to a file, we can use Jump to source (or CMD-click) to open it in a new editor tab.

If you run the request again, the link to the second response appears. What if you wanted to compare these responses? Simply click the gutter icon or use the Compare intention action to open the files in the Differences viewer.

request_results_compare

Let’s try another example. There’s no need to create a new file for that: simply use ‘###’ as a separator between requests.

request_from_file

This request will return nothing of particular interest when executed, but it still illustrates several capabilities of HTTP request syntax:

  • You can use comments inside your requests – just make sure to start each comment line with ‘#’ or ‘//’.
  • You can break long query strings into several lines by indenting all but the first line of the string.
  • You can use the left angle bracket (‘<’) and provide the path to a file, test.json in our case. The request body will then be sent from the specified file.

As you may remember, we have been executing our requests from a scratch file. Such files are commonly used in the development process. If you want to include your request inside the project and share it with your team, move it to a physical file. Invoke the Move refactoring and specify the destination:

move_request

That’s it! The created file will be stored inside the project. Physical files are primarily used for documenting HTTP requests and are not modified by the IDE. Therefore, when you run a request from a physical file, you will not see the link to the response below the request itself. To view responses, you will need to use Requests history, so let us explore that right away.

After a hard day’s work, you may want to review the requests that have been run. Simply click the Show HTTP requests history button in the top-right corner of the editor (or use the Tools menu command with the same name). The http-requests-log file will open, showing you the 50 most recently run requests and responses and allowing you to re-run any of them:

requests_history

Future plans

In this post, we’ve really only scratched the surface of what’s possible with the new REST client. We encourage you to try it and hopefully have an easier time testing and debugging your web services.

Please bear in mind that we’ve only started working on the new REST client. Expect a lot more features to come in future releases, such as variables inside requests, in-place documentation for Header Fields, live templates, refactorings, inspections, importing and exporting requests, and many more.

Stay tuned!

This entry was posted in Cool Feature, Newsletter, PhpStorm, Tutorial and tagged . Bookmark the permalink.
  • http://www.polskieszlaki.pl Łukasz Piernikarczyk

    Great plan but… when I start rest request from file breakpoints are not working :/
    Can I somehow copy request from file to REST client tab?
    And one more think – “{” in http path breaks code… ex.: GET http://api.system.local/finanse/kurs?warunki={“do_wyslania”:{“wartosc”:1}}&waluta=EUR

  • mesilov

    Can you add this cool staff to work with swagger files?

  • Kostadin

    Cool. General and per request download directory option will useful. And maybe it will be useful to create folder by the Y-m-d format and inside the files (activated by option?).

  • User

    When are you planning on releasing it for Intellij IDEA?

  • BoxOfSnoo

    How do you post something that’s NOT json? e.g. x-www-form-urlencoded

    • Maxim Kolmakov

      Please use something like:
      POST http://127.0.0.1:8000/foo.php
      Content-Type: application/x-www-form-urlencoded

      FOO=BAR
      ###

      • BoxOfSnoo

        More precisely

        FOO=BAR
        &BAZ=QUX

        when more than one parameter is required (i.e. all the time). I will have to figure out multipart too…

    • nepda

      POST https://example.com/api/v3/poster
      content-type:application/x-www-form-urlencoded

      field=value&other=val2

  • Yevgeny Tomenko

    Hello Anton. I think most useful feature for client would be post-request section with scripting language that allow to build some asserts based response.

  • Artem Lukanin

    What about Kerberos? I still have to run “curl –negotiate” from the IDEA console…

  • Art Sir

    I’m on version phpstorm 2017.4 when i create a new scratch I dont see the option to select the language HTTP request

    • Eugene Morozov

      There’s no 2017.4 yet, you must be on 2017.2.4, and this functionality is only available in 2017.3 EAP.

      • Art Sir

        thank you, you are right i was on 2.4. I’ll upgrade thank you.

  • errogaht

    Can i send files via POST multipart/form-data & can you provide an example?

  • Paul Dixon

    This is really nice – it would be great if there was some way to chain requests together and use the JSON response from one request to construct the next. For example, you could talk to an OAuth secured API by first getting an access token, then making an API request with that token.

    Here’s one way that could work, by indicating that the response should be stored in a variable ‘$oauth’ for use in later requests

    POST https://example.com/oauth/v2/token
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic 1234567890abcedf
    X-PHPStorm-Store-JSON: $oauth <—- here we tell PHPStorm to remember the JSON response

    grant_type=client_credentials

    ###

    GET https://example.com/api
    Authorization: Bearer {$oauth-access_token} <— here we extract data from a previous response
    Accept: application/json

    Coupled with a 'run all requests' capability, this would provide a very rapid method of trying a sequence of API calls.

    • GK

      Upvoting for “run all requests” and “chain requests together”

  • Emptyfruit

    The described feature of saving the result to a file is not working with Idea 2017.3. After successful run i only get the result in Run window and no link to result file appears. Thus, i have no option to compare results and also there is nt ‘format json’ option in Run window, only soft wraps, so it is hard to view large json response.

  • Alexander Klimetschek

    I have IntelliJ IDEA 2017.3 (Ultimate Edition, Build #IU-173.3727.127) but I don’t see an “HTTP” or “REST” option when creating a scratch file. If I create a normal file with an “http” extension it says it is an unknown format and asks me to assign it one (but there is no HTTP or REST option either).

    • Alexander Klimetschek

      Ok, got it now, I had to enable/install the “REST Client” plugin first. Maybe it wasn’t enabled because I was upgrading from 2017.2.

  • ymalcev

    Do *.rest and *.http files require Jetbrains IDEs to be used, or there is some other way to run them? We’re considering this feature as an alternative to shared collections in Postman, but we want to be sure it can be used also by non-coders, who does not use IDEs in their daily work.

    • Dmitry Tronin

      Well, that’s a Jetbrains IDEs implementation of .http and .rest files usages in a REST context. So yes: you would require our IDE to utilize the functions described in this blog post.

  • Александр Владимирович

    Thank you for this great plugins

  • http://dontgiveafish.com Anton Bagaiev

    That’s a nice feature to document APIs! Can I beautify the text of JSON response?

  • Brandon Saunders

    How do I write the result out to file?

    POST https://httpbin.org
    /post

    > testing.json

    • Brandon Saunders

      Nevermind. I figured it out. Look inside the .idea folder, and then in the httpRequests folder.

  • Igor Nikolaev

    Would be really nice to be able to call some external program and substitute the result. For example in my case I need to be able to substitute authentication token which is generated by a script because token expires after an hour.

  • Anton Matviyenko

    Wonderful feature guys! Could you send the GET request with a body? This is really useful for playing with Elastic Search or another WEB API.

  • Rodion Chernyshov

    Cool feature!!!
    Dear jetbrains, could you please tell me is there any way to switch from http to https depending on the environment?
    Ex:

    Development:

    GET http://text.com/api

    Stage:

    GET https://text.com/api