obsidian-plugin/rooyca_obsidian-api-request
1
0
Fork 0
mirror of https://github.com/rooyca/obsidian-api-request.git synced 2026-07-22 07:50:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update(docs): first web for docs

Browse source
This commit is contained in:
rooyca 2024-05-09 13:53:01 -05:00
parent f1b9b3e13d
commit 577774edef
5 changed files with 299 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
.github/workflows/documentation.yml vendored Normal file
View file

@ -0,0 +1,18 @@
name: docs
on:
release:
types:
- published
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: 3.x
- run: |
pip install mkdocs-material
cd docs
mkdocs gh-deploy --force

111
README.md
View file

@ -1,21 +1,21 @@
# APIR - Api Request
# APIR - API Request
Obsidian plugin that allows you to make requests to APIs and receive responses in the format of a JSON block or an Obsidian variable.
Obsidian plugin that allows you to make requests to API's and receive responses in code-blocks or store them in `localStorage`.
> [!IMPORTANT]
>
> We now support JSON, TEXT and MARKDOWN responses
> JSON, TEXT, HTML and MARKDOWN responses supported
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/rooyca/obsidian-api-request?logo=github&color=ee8449&style=flat-square)](https://github.com/rooyca/obsidian-api-request/releases/latest)
[![Obsidian plugin release](https://img.shields.io/badge/Obsidian%20plugin%20release-purple?logo=obsidian&style=flat-square)](https://obsidian.md/plugins?id=api-request)
![conf_img](apir.gif)
![req_img](req-codeblock.gif)
## Installation
The plugin can be installed from within Obsidian or manually.
The plugin can be installed from within Obsidian.
### Obsidian Community Plugin Browser (Recommended)
### Obsidian Community Plugin Browser
- Go to `Settings` -> `Community plugins`
- Make sure `Restricted mode` is **off**
@ -27,31 +27,16 @@ The plugin can be installed from within Obsidian or manually.
There are two ways to use the plugin:
### With Markdown Block (Easier)
### With Code-blocks
To use the plugin, create a code block with the language set to `req`. Inside the code block, you can specify things like the URL, request method, request data, headers, and the response data you want to display.
To use it, create a code-block with the language set to `req`. Inside the code-block, you can specify `url`, `method`, `body`, `headers`, `format`, etc. For more information check [documentation](https://rooyca.github.io/obsidian-api-request).
| Key| Description| Default|
| ---| -----------|---------|
| disabled | Disables the request| |
| req-id | Where response is store | req-general |
| url | The URL to send the request to (You can use variables defined in the frontmatter)| |
| method | Request method (GET, POST, PUT, DELETE)| GET |
| body | Data to send with the request. Data should by in JSON format (You can use variables defined in the frontmatter)| |
| headers | Header(s) for the request. Data should by in JSON format (You can use variables defined in the frontmatter)| |
| show | Response data to display. You can use a right arrow `->` to access nested objects| ALL |
| format | Format in which the response should be displayed| `{}` |
| response-type | The type of response we are getting (json, txt or md)| json |
The plugin will automatically replace the code block with the response from the API. Here are a quick examples:
If you want to show data from nested objects, you can do that by using a right arrow `->`. For example, if you want to show the `last` from the `chess_daily` object, you can do that like this:
```req
url: https://api.chess.com/pub/player/hikaru/stats
show: chess_daily -> last -> rating
```
It's also posible to show multiple outputs by separating them with a comma:
Multiple outputs can be displayed:
```req
url: https://api.chess.com/pub/player/hikaru/stats
@ -59,124 +44,88 @@ show: chess_daily -> last -> rating, chess_daily -> best -> rating
format: <p>Last game: {}</p> <strong>Best game: {}</strong>
```
You can show the entire response by only specifying the url:
```req
url: https://jsonplaceholder.typicode.com/todos/1
```
Or you can loop over an array. The following example will give you the city from all users:
It's possible to loop over an array.
```req
url: https://jsonplaceholder.typicode.com/users
show: {..} -> address -> city
```
You can use the frontmatter variables in the URL, for instance, if you have a variable `numb` defined in the frontmatter, you can use it like this:
```req
url: https://jsonplaceholder.typicode.com/todos/{{this.numb}}
```
You can specify the response type you are getting:
```req
url: https://raw.githubusercontent.com/Rooyca/Rooyca/main/README.md
response-type: md
```
You can also specify the request method, request data, headers, and the response format:
Here is a more complex example:
```req
url: https://my-json-server.typicode.com/typicode/demo/comments
format: Here: <h1>{}</h1> is the ID
format: <h1>{}</h1>
method: post
body: {"id":1}
headers: {"Accept": "application/json"}
show: id
```
In the example above, the response will be displayed in a h1 tag.
Responses can be stored in `localStorage` with the `req-id` flag.
---
Now we can store the response in `localStorage` and use it in other blocks. For example, if we want to store the response in a variable called `idPersona`:
```req
url: https://jsonplaceholder.typicode.com/users/1
show: id
req-id: idPersona
req-id: id-persona
```
With this with can also disable a request and still get the response:
```req
url: https://jsonplaceholder.typicode.com/users/1
show: id
req-id: idPersona
disabled
```
This will check for the response in the `localStorage` and if it's not there, it will make it.
#### How to get responses from localStorage
For this you'll need [dataview](https://obsidian.md/plugins?id=dataview).
```dataviewjs
dv.paragraph(localStorage.getItem("req-idPersona"))
dv.paragraph(localStorage.getItem("req-id-persona"))
```
Is mandatory to use `req-` before whatever you defined in `req-id` flag.
You could also used inline:
`$=localStorage.getItem("req-idPersona")`
But this is a little buggy and don't work all the time. (Use this for short and unformated responses)
`$=localStorage.getItem("req-id-persona")`
But this is a little buggy and don't work all the time. (Use this for short and unformatted responses)
#### How to remove responses from localStorage
In order to remove a response from the `localStorage` you can use the following code:
```dataviewjs
localStorage.removeItem("req-idPersona")
localStorage.removeItem("req-id-persona")
```
Or you can use the following code to remove all responses:
For removing all responses use:
```dataviewjs
localStorage.clear()
```
**There is also a button in the settings to remove all responses.**
Or just go to the plugin settings and click the button `Clear ID's` to remove all responses.
### With Configuration
To use the plugin, press `Ctrl+P` and search for "APIR". The plugin will present you with two options:
To use the plugin, press `Ctrl+P` and search for `APIR`. There are two options:
1. Show response in modal
2. Paste response in current document (at current line)
Select the option that suits your needs. Additionally, you can configure the plugin to output the response in either JSON block format or as an Obsidian variable. This option can be accessed through the plugin's settings.
#### Settings
The plugin has a few settings that you can configure:
- **URL**: The URL to send the request to.
- **Format Output**: Just JSON blocks (for now).
- **Method**: Choose between GET, POST, PUT & DELETE.
- **Body**: The data to send with the request. Data should by in JSON format.
- **Headers**: The header data to send with the request. Data should by in JSON format. (`{"Content-Type": "application/json", "Authorization": "Bearer TOKEN"}`)
- **Response**: The response data to display. If empty all data will be display. You can use a right arrow `->` to access nested objects. For example, if you want to show the `title` from the `user` object, you can do that like this: `user -> title`.
![req_settings](config_img.png)
- URL: The URL to send the request to.
- Format Output: Just JSON blocks (for now).
- Method: Choose between GET, POST, PUT & DELETE.
- Body: The data to send with the request. Data should by in JSON format.
- Headers: The header data to send with the request. Data should by in JSON format. (`{"Content-Type": "application/json", "Authorization": "Bearer TOKEN"}`)
- Response: The response data to display. If empty all data will be display. You can use a right arrow `->` to access nested objects. For example, if you want to show the `title` from the `user` object, you can do that like this: `user -> title`.
## To-do
- [x] Add more request types (POST, PUT, DELETE)
- [x] Add support for authentication
- [x] Add customizability for modal output (e.g. show only specific fields, change color scheme, add custom CSS)
- [x] Add customizability for variable output (e.g. show only specific fields, change variable name)
- [x] Add customization for modal output
## Feedback and Contributions

195
docs/docs/codeblock/flags.md Normal file
View file

@ -0,0 +1,195 @@
# Code-block 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 | `{}` |
| response-type | json |
| req-id | req-general |
| disabled | |
## url
Is the only **required** flag. It specifies the endpoint of the request. Variables defined in the `frontmatter` can be used.
~~~markdown
```req
url: https://jsonplaceholder.typicode.com/users/{{this.id}}
```
~~~
!!! info "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
~~~markdown
```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.
~~~markdown
```req
url: https://jsonplaceholder.typicode.com/posts
method: post
body: {"title": {{this.title}}, "body": "bar", "userId": 1}
```
~~~
!!! info "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.
~~~markdown
```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`.
~~~markdown
```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.
~~~markdown
```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>
```
~~~
Looping over an array is also possible using `{..}`. The following example retrieves the city from all users.
~~~markdown
```req
url: https://jsonplaceholder.typicode.com/users
show: {..} -> 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.
~~~markdown
```req
url: https://jsonplaceholder.typicode.com/posts/1
show: title, body
format: <h1>{}</h1> <p>{}</p>
```
~~~
!!! info "In this example, first `{}` will be replaced by the title, and second `{}` will be replaced by the body."
## response-type
Specifies the type of response we are getting. The default value is `json`. The available values are:
- json
- md
- txt
When the response type is `md`, the response will be rendered as markdown.
~~~markdown
```req
url: https://raw.githubusercontent.com/Rooyca/Rooyca/main/README.md
response-type: md
```
~~~
## 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.
~~~markdown
```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).
~~~markdown
```req
url: https://jsonplaceholder.typicode.com/users/1
req-id: name
disabled
```
~~~
Responses can also be accessed using [dataview](https://blacksmithgu.github.io/dataview/).
~~~markdown
```dataview
dv.paragraph(localStorage.getItem("req-name"))
```
~~~
!!! info "Is mandatory to use `req-` before whatever you defined in `req-id` flag."
To remove responses from localStorage, run:
~~~markdown
```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.
~~~markdown
```req
url: https://jsonplaceholder.typicode.com/users/1
show: name
req-id: name
disabled
```
~~~

31
docs/docs/index.md Normal file
View file

@ -0,0 +1,31 @@
# Overview
APIR (shorthand for api-request) is an [Obsidian](https://obsidian.md/) plugin that allows you to make requests and show the responses in your notes. This aims to be an easy way to integrate APIs into your notes.
## How to use
### Code-block
To use it, create a code-block with the language set to `req`. Inside the code-block, you can specify `url`, `method`, `body`, `headers`, `format`, etc. See the [available flags](codeblock/flags) for more information.
~~~markdown
```req
url: https://my-json-server.typicode.com/typicode/demo/comments
method: post
body: {"id":1}
headers: {"Accept": "application/json"}
show: id
format: <h1>{}</h1>
req-id: id-persona
disabled
```
~~~
### Configuration (don't have all functionalities yet)
!!! info "All parameters can be defined in settings."
Press `Ctrl+P` and search for `APIR`. There are two options:
1. Show response in modal
2. Paste response in current document (at current line)

25
docs/mkdocs.yml Normal file
View file

@ -0,0 +1,25 @@
site_name: APIRequest
repo_url: https://github.com/Rooyca/obsidian-api-request/
markdown_extensions:
- admonition
theme:
features:
- content.code.copy
name: material
palette:
- scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
- scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode
nav:
- Getting started: 'index.md'
- codeblock:
- flags: 'codeblock/flags.md'