Run and Test HTTP API Requests

A few weeks ago I saw the front page hacker news posts In a new text-based HTTP runner based on CURL and written in Rust. throw. Interesting! We were looking for a simpler way to fire and test API requests against our social API.

If you want to test your API calls first, you have a number of options, including online test tools, Postman, and building your own. Here’s a Google search for testing API calls.

These tools can be great, but we want to keep them simple.

• Call API endpoints with query or post parameters.
• Check the 200 response.
• Check the returned JSON.
• Call another API endpoint based on the JSON returned by the previous call.

The system should run through all endpoints and alert you if something goes wrong. Execution can be just before release or right after a code change. And I’m a terminal/CLI aficionado, so I prefer running tests from the command prompt. slopeMy favorite Mac terminal app.

Hurl for testing API endpoints

When I saw Hurl I thought wow this might be perfect. Although I have something to say about the name.

As Hurl describes himself

“”Hurl can execute HTTP requests defined in plain text format. It can be used to assert responses along the way by fetching data or replaying scenarios (request sequences). Targeted both devops and developers in text format. Targeted for local development and continuous integration via command line usage/simple native binaries.”

Let’s try Hurl. you can also See how to run Hurl with script example.

Basic Hull Call

first install Run Hurl on the OS of your choice. Here brew On Mac:

brew install hurl

Now let’s make a call. Make a call to google.com to see if a 200 response is returned.

Create a file called basic.throw In your favorite IDE – there is no VSCode syntax highlighter, but the Hurl team said they are working on it.

GET https://www.google.com
HTTP/1.1 200

in the directory basic.throw Once the file is saved, run the following command.

hurl --test basic.hurl

The response is:

error! But this is good. As you can see the problem is the google.com response using HTTP/2. Also note how to get stats on how many files have been executed, duration, etc. Just change this in your basic.hurl file and you can start racing.

Advanced Hull Cole

Now we do the fun stuff of calling the POST API with the body and checking the result. In this advanced Hurl example, we will be calling Ayrshare’s social media API to send a post. you can make free account to your API key. After creating an account, connect one or more social networks, such as Twitter.

Create a new file called Post. Huh Copy the following code.

# /post POST -------------
POST https://app.ayrshare.com/api/post
Content-Type: application/json
Authorization: Bearer {{API_KEY}}
{
    "randomPost": true,
    "platforms": [
        "twitter"
    ]
}

HTTP/* 200
[Asserts]
header "Content-Type" == "application/json; charset=utf-8"
jsonpath "$.status" == "success"
jsonpath "$.errors" count == 0

jsonpath "$.postIds[0].status" == "success"
jsonpath "$.postIds[0].id" exists
jsonpath "$.postIds[0].postUrl" exists
jsonpath "$.postIds[0].platform" == "twitter"

jsonpath "$.id" exists
jsonpath "$.refId" exists
jsonpath "$.post" exists

[Captures]
id: jsonpath "$['id']"
tw_id: jsonpath "$.postIds[0].id"
# -----------------------

A number of things are happening. first, {{API_KEY}} Variables set in the env file. Keep it in another file for use with other Hurls.

Set your API key in a file called vars.env:

API_KEY=GHLOM-QW6MRC7-KX944W1-PWKJFT

The next two lines (Content-Type and Authorization) to set the headers and the JSON body of the POST. reference Social media API /post endpoint More about POST body, this is all the data related to making the call.

with line HTTP/* 200 Start testing (* allows any HTTP version instead of 1.1 or 2).

[Asserts]

at [Asserts] Test the validity of headers and JSON responses in sections of the file. header "Content-Type" Make sure the content type is correct. For JSON, you need to extract the key. jsonpath Query, predicate type and predicate value.

for example, jsonpath "$.status" == "success" Get the status key and check if the value is “success”. If not, an error occurs.

There are several types of predicates: exists and count.

[Captures]

that much [Captures] Sections capture data into variables. The format is:

in this example

id: jsonpath "$['id']"
tw_id: jsonpath "$.postIds[0].id"

Capture the returned post id and tweet id in an object in an array. You can use this variable later if you want to concatenate your request in a form. {{variable name}}:

# /analytics/post -------
POST https://app.ayrshare.com/api/analytics/post
Content-Type: application/json
Authorization: Bearer {{API_KEY}}
{
    "id": "{{id}}"
}

run

Finally, we need to run the Hurl file from the command prompt. --very-verbose Flag it so you can see all the good things happen.

hurl --test --very-verbose --variables-file vars.env post.hurl

result:

happy throw

So far Hurl has been very good. I found it easy to use and feature-rich. Also they seem to be released regularly. That’s always a good sign.

We’ve been writing more test cases over the past few weeks, and as our development team uses Hurl more, we’ll decide if it’s a permanent part of our test suite.

For more sample Hurl files with chaining, check out: Hurl files from Ayrshare.

— Geoff Bourne, co-founder of Ayrshare