👨🏻‍💻 Codeblocks

The codeblock is a versatile block that can be used to write code in different languages. In this case, we will use it to make requests.

🏳️ Flags

Flags are the way to specify the parameters of our request and also the format in which we want our response.

Flag	Default
url
method	GET
body
headers
show	ALL
format	{}
req-id	req-general
disabled
req-repeat	1t@1s
notify-if
save-to
properties
render	false
res-type

url

Is the only required flag. It specifies the endpoint of the request. Variables defined in the frontmatter can be used.

```req 
url: https://jsonplaceholder.typicode.com/users/{{this.id}}
```

Where {{this.id}} is a variable (id) defined in the frontmatter.

method

Specifies the request method. The default value is GET and the available values are:

• GET
• POST
• PUT
• DELETE

```req 
url: https://jsonplaceholder.typicode.com/posts
method: post
```

body

Specifies the body of the request. The default value is an empty object. The data should be in JSON format with double quotes separating the keys and values with a colon and space. Variables defined in the frontmatter can be used.

```req 
url: https://jsonplaceholder.typicode.com/posts
method: post
body: {"title": {{this.title}}, "body": "bar", "userId": 1}
```

Where {{this.title}} is a variable (title) defined in the frontmatter.

headers

Specifies the headers of the request. The default value is an empty object. The data should be in JSON format with double quotes separating the keys and values with a colon and space. Variables defined in the frontmatter can be used.

```req 
url: https://jsonplaceholder.typicode.com/posts
method: post
headers: {"Content-type": "application/json; charset=UTF-8"}
```

show

Specifies the response data to display. Accessing nested objects is done using a right arrow ->. The default value is ALL.

```req
url: https://api.chess.com/pub/player/hikaru/stats
show: chess_daily -> last -> rating
```

Multiple outputs can be displayed by separating them with a comma.

```req
url: https://api.chess.com/pub/player/hikaru/stats
show: chess_daily -> last -> rating, chess_daily -> best -> rating
format: <p>Last game: {}</p> <strong>Best game: {}</strong>
render
```

Looping over an array is also possible using {..}. The following example retrieves the city from all users.

```req 
url: https://jsonplaceholder.typicode.com/users
show: {..} -> address -> city
```

Looping over a specified number of elements of the array is also possible using {n..n}.

```req 
url: https://jsonplaceholder.typicode.com/users
show: {0..2} -> address -> city
```

It's also possible to loop over a specified range of indexes of the array using {n-n-n}.

```req 
url: https://jsonplaceholder.typicode.com/users
show: {0-2-1} -> address -> city
```

format

Specifies the format in which the response should be displayed. The default value is {}. It can be any string (including markdown and html). If more than one output is specified, more then one format should be specified, otherwise, the same format will be applied to all outputs.

```req 
url: https://jsonplaceholder.typicode.com/posts/1
show: title, body
format: <h1>{}</h1> <p>{}</p>
render
```

In this example, first {} will be replaced by the title, and second {} will be replaced by the body.

req-id

Specifies the id of the request. The default value is req-general. This is useful when we want to store the response in localStorage and use it in other blocks or notes.

```req 
url: https://jsonplaceholder.typicode.com/users/1
show: name
req-id: name
```

Stored responses can be accessed using the req-id with the disabled flag (which won't trigger a new request).

```req 
url: https://jsonplaceholder.typicode.com/users/1
req-id: name
disabled
```

Responses can also be accessed using dataview.

```dataview
dv.paragraph(localStorage.getItem("req-name"))
```

Is mandatory to use req- before whatever you defined in req-id flag.

To remove responses from localStorage, run:

```dataview
localStorage.removeItem("req-name")
```

To remove all responses, go to settings and click on the Clear ID's button.

disabled

Disables the request. If a req-id is specified, APIR will check for the response in localStorage. If it's not found, it will make a new request and store it. After that, APIR will use the stored response.

```req 
url: https://jsonplaceholder.typicode.com/users/1
show: name
req-id: name
disabled
```

req-repeat

This only works with JSON responses

Specifies the number of times the request should be repeated and the interval between each repetition. The default value is 1@1 (read as X time(s) every X second(s)).

```req 
url: api.coincap.io/v2/rates/bitcoin
req-repeat: 5@5
render
```

notify-if

This only works with JSON responses

Specifies the condition to trigger a notification. Can be used to monitor a specific value. The path syntax used to access nested objects varies from the show flag, here dots are used instead of arrows and not spaces are allowed in the path.

```req 
url: api.coincap.io/v2/rates/bitcoin
req-repeat: 5@5
notify-if: data.rateUsd < 69889
render
```

In the example above, a notification will be triggered everytime the value of data.rateUsd is less than 69889.

save-to

Specifies the path to save the response. It'll save the entire response. A file extension is required. It won't create directories.

```req 
url: https://jsonplaceholder.typicode.com/posts/1
save-to: posts/1.json
```

properties

To use this flag you need a JSON response and the show flag

Specifies the frontmatter properties to update with the response. The data should be strings separated by commas. To set internal links use the [[..]] syntax.

```req 
url: https://jsonplaceholder.typicode.com/posts/1
show: id, title
properties: id, title
```

render

If present the response will be rendered as HTML. It's useful when the response is an image or a table. The HTML is sanitized to prevent XSS attacks.

```req 
url: https://jsonplaceholder.typicode.com/photos/1
show: url
format: ![img]({})
render
```

res-type

Specifies the type of the response. If this flag is not present the plugin will try to guess the type based on the response content-type. This could be used as an optional fallback feature.

```req 
url: https://jsonplaceholder.typicode.com/posts/1
res-type: json
```