Skip to content

Quick Start

This document will walk you through the process of using yurl and explore its various features.

We will use the JSONPlaceholder API as an example, which is publically available, so you can follow along with the examples on your own.

Basic

Let's start with the most basic example.

Create a http.yaml file with the following content:

http.yaml
1
2
3
4
5
6
7
8
9
config:
  host: jsonplaceholder.typicode.com
  port: 443
  scheme: https

requests:
  ListTodos:
    method: GET
    path: /todos

We define a single request named ListTodos which will list all the todos from the JSONPlaceholder API.

Now, let's run the following command:

1
yurl ListTodos

yurl by default detects the http.yaml file and executes the ListTodos request.

Request with user input

Now we define a request to fetch a single todo by its id. We will define the id parameter as a variable.

http.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
config:
  host: jsonplaceholder.typicode.com
  port: 443
  scheme: https

requests:
  ListTodos:
    method: GET
    path: /todos

  GetTodo:
    method: GET
    path: /todos/{{ id }}

We define a single request named GetTodo which will fetch a single todo by its id. We use variables to get the id from the user.

Learn more about variables here.

Verbose Mode

You can run the requests in verbose mode by passing the -v flag.

1
yurl -v GetTodo

List Requests

We can list all the requests defined in the http.yaml file by running yurl ls command.

1
yurl ls

Post Request with JSON Body

Let's define a request to create a new todo. We will use the POST method and pass a JSON body as the payload.

http.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
config:
  host: jsonplaceholder.typicode.com
  port: 443
  scheme: https

requests:
  ListTodos:
    method: GET
    path: /todos

  GetTodo:
    method: GET
    path: /todos/{{ id }}

  CreateTodo:
    method: POST
    path: /todos/
    jsonBody: |
      {
        "title": "{{ title }}"
      }

jsonBody automatically sets the Content-Type header to application/json.

Enforcing types on user input variables

We can enforce types on user input variables by specifying the type following the format <varname:type>.

http.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
config:
  host: jsonplaceholder.typicode.com
  port: 443
  scheme: https

requests:
  ListTodos:
    method: GET
    path: /todos

  GetTodo:
    method: GET
    path: /todos/{{ id }}

  CreateTodo:
    method: POST
    path: /todos/
    jsonBody: |
      {
        "title": "{{ title }}",
        "userId": "{{ userId:int }}
      }

Type of variable is displayed in the prompt.

If the user enters a value of a different type, the request will fail.