Testing an API with emacs and restclient

We can execute this code using C-c C-c to show the results in the current buffer or use C-c C-v to show them in a new buffer.

GET http://localhost:5000/?name=guest
Content-Type: application/json

Result:

Hello, guest!
<!-- GET http://localhost:5000/?name=guest -->
<!-- HTTP/1.0 200 OK -->
<!-- Content-Type: text/html; charset=utf-8 -->
<!-- Content-Length: 13 -->
<!-- Server: Werkzeug/0.16.0 Python/3.6.9 -->
<!-- Date: Tue, 29 Oct 2019 05:34:44 GMT -->
<!-- Request duration: 0.023261s -->

As we can see we can define a http request in plain text. We just need to define the method and the URL of our API. In this case we're querying the root of the API. Also the response is presented in plain text including some useful data like http headers and the request duration. We can define the http request headers as well.

In this case the response use an html format as we can see in the Content-Type response header.

Note: when you create a file with many requests in it make sure you split them using a comment #, for example:

GET http://localhost:5000/?name=foo
# a split
GET http://localhost:5000/?name=bar
# a split
GET http://localhost:5000/?name=baz

If you don't add a separator an error will be raised when you try to execute the request.

Now lets try to fetch a json type endpoint. Restclient identifies the content-type of the response and use an emacs mode that fits with the content-type. In this case the response is a json object so restclient enable js-mode to present the response.

GET http://localhost:5000/api
Content-Type: application/json

Result:

{
  "version": 1.0
}
// GET http://localhost:5000/api
// HTTP/1.0 200 OK
// Content-Type: application/json
// Content-Length: 16
// Server: Werkzeug/0.16.0 Python/3.6.9
// Date: Tue, 29 Oct 2019 05:42:01 GMT
// Request duration: 0.025286s

Let's try with another endpoint that has more interesting information.

GET http://localhost:5000/api/items
Content-Type: application/json

Result:

{
  "data": [
    {
      "name": "item 1",
      "uid": "931d90b493e944d9816061f46b57ce92"
    },
    {
      "name": "item 2",
      "uid": "edf9c8dda1ed4e8da205c53d9978ede2"
    },
    {
      "name": "item 3",
      "uid": "57a5146e3c98479785374f38e9e4c056"
    }
  ]
}
// GET http://localhost:5000/api/items
// HTTP/1.0 200 OK
// Content-Type: application/json
// Content-Length: 188
// Server: Werkzeug/0.16.0 Python/3.6.9
// Date: Tue, 29 Oct 2019 05:42:33 GMT
// Request duration: 0.026217s

What happen if we need to pass some extra information to make an http request? In restclient we can have variables and we use them in the definition of the request. In this case we'll define a password variable which contains the required Authorization value to be able access to this endpoint. Also we can define the payload of the request, in this case a json object.

First let's try a wrong password to see what happen.

:password = wrong-password

POST http://localhost:5000/api/items
Content-Type: application/json
Authorization: :password
{
    "name": "new item"
}

Result:

{
  "error": "please provide credentiales"
}
// POST http://localhost:5000/api/items
// HTTP/1.0 401 UNAUTHORIZED
// Content-Type: application/json
// Content-Length: 40
// Server: Werkzeug/0.16.0 Python/3.6.9
// Date: Tue, 29 Oct 2019 05:47:24 GMT
// Request duration: 0.036553s

We received a 401 response because the credentiales we used are not correct. Now let's try it again but now with the correct credentials.

:password = password

POST http://localhost:5000/api/items
Content-Type: application/json
Authorization: :password
{
    "name": "new item"
}

Result:

{
  "data": {
    "name": "new item",
    "uid": "f1ede16e39754b3eb735627e78d26146"
  }
}
// POST http://localhost:5000/api/items
// HTTP/1.0 201 CREATED
// Content-Type: application/json
// Content-Length: 70
// Server: Werkzeug/0.16.0 Python/3.6.9
// Date: Tue, 29 Oct 2019 05:48:15 GMT
// Request duration: 0.034962s

As we can see the request was made successfully. Variables in restclient are evaluated at the time the request is made so we can define a variable and use it in as many requests as we want. This is useful when we're working with APIs that need some authentication to allow us to access to their endpoints. We can request a token then save it and use it for the rest of the request we've defined in our file.

If we need to pass a request with its data to some friend who doesn't use emacs we can pass the request definition(it's just plain text after all) but we can also generate a curl command so it's going to be easy for anyone to test the request.

We can use C-c C-u from within out request to generate a curl command. After we execute this keybinding the curl command will be copied to the clipboard.

If we use this in our previous example we'll get the following curl command:

  curl -i -H Authorization\:\ password -H Content-Type\:\ application/json -XPOST http\://localhost\:5000/api/items -d \{'
  '\ \ \ \ \"name\"\:\ \"new\ item\"'
  '\}

Now we can paste this in a terminal and the request will be made.

From the same author we have restclient-helm this package allow us to jump easily to a specific request using the combination C-c C-g. This is useful if we are working with an extensive API and we want to find some request quickly.

This package use helm to present the available options and when we chose one the cursor will jump to the selection.

If we are using json as the request body we'll need to have it formatted in some way. We can use json-mode for accomplish this.

Now our installation code will be:

(use-package json-mode
  :ensure t)

(use-package restclient
  :ensure t
  :defer t
  :mode (("\\.http\\'" . restclient-mode))
  :bind (:map restclient-mode-map
	      ("C-c C-f" . json-mode-beautify)))

We're adding a new keybinding to restclient-mode-map so we can use C-c C-f to format the request body.