Restler is a file based REST API client. If you are familiar with tools like Postman, Insomnia, or curl, then you will feel right at home with Restler. This is file based, opinionated, command line tool. Please follow Installation and Usage guide to get started.
curl -s https://raw.githubusercontent.com/shrijan00003/restler/main/install/darwin-amd64.sh | bash
curl -s https://raw.githubusercontent.com/shrijan00003/restler/main/install/darwin-arm64.sh | bash
curl -s https://raw.githubusercontent.com/shrijan00003/restler/main/install/linux-amd64.sh | bash
1. Initialization using restler init
:
- Usage: Run
restler init
in your terminal. - Prompt: You'll be prompted to enter the desired project name.
- Example: If you enter
collection
, a folder namedcollection
will be created in your current directory. This folder includes default files and subfolders for your API collection. - Configuration:
- The
.env
file will be created withRESTLER_PATH=collection
to specify the project directory. - The
.gitignore
file will be updated to ignore environment and response files from version control.
- The
2. Manual Project Structure Creation:
- API Collection Folder: Create a folder for your API collection. The default name is
restler
, but you can choose a different name. - Request Folder Structure:
- Create a subfolder named
requests
inside the API collection folder. - Within the
requests
folder, create subfolders for each API request (e.g.,requests/posts
). - Inside each request subfolder, create a YAML file with the extension corresponding to the HTTP method:
.<http-method>.yaml
(e.g.,posts.post.yaml
for a POST request orposts.get.yaml
for a GET request).
- Create a subfolder named
- Environment Variables (Optional):
- Create an
env
folder inside the API collection folder. - Within the
env
folder, create a YAML file for environment variables (e.g.,env/default.yaml
). - This allows you to define and use environment variables in your API requests.
- Create an
- Configuration (Optional):
- A
config.yaml
file can be created in the API collection folder to store configurations like the default environment.
- A
- Runtime Environment Variable:
- To change the project directory at runtime, set the
RESTLER_PATH
environment variable. - Example:
export RESTLER_PATH=app-prefix-collection
- To change the project directory at runtime, set the
- Running Requests:
- Use the
restler
command followed by the HTTP method and request name to execute the desired request. - Example:
restler p posts
executes a POST request defined inposts.post.yaml
, whilerestler g posts
executes a GET request fromposts.get.yaml
.
- Use the
This approach allows for a more customized project structure and configuration for your specific needs.
- Create a folder for the API collection, default is
restler
. - Create a folder
requests/<request-name>
likerequests/posts
inside the API collection folder and create a request file inside it. - Create a request file with
.<http-method>.yaml
extension. For exampleposts.post.yaml
, orposts.get.yaml
- (Optional) Create
env
folder inside the API collection folder and create a.yaml
file inside it. For exampleenv/default.yaml
for using environment variables in request. - (Optional) Create
config.yaml
file inside the API collection folder for configurations like environment. - (Optional) Change folder for API collection in runtime by setting
RESTLER_PATH
environment variable. For exampleexport RESTLER_PATH=app-prefix-collection
- Run
restler <http-method> <request-name>
to run the request. For examplerestler psot posts
to run post request andrestler get posts
to run get request. - Check the output files in
requests/<request-name>
folder. For examplerequests/posts/.<request-name>.post.res.md
for post response andrequests/posts/.get.res.txt
for get request response. - for other supports please check the TODO file.
restler post <request-name>
orrestler p <request-name>
restler get <request-name>
orrestler g <request-name>
restler patch <request-name>
orrestler m <request-name>
restler put <request-name>
orrestler u <request-name>
restler delete <request-name>
orrestler d <request-name>
restler --help
orrestler -h
or orrestler -h
restler --version
orrestler -v
Now all our REST method commands supports following flags:
env
flag is compatible for selecting environment from the command line. If we don't pass this option in command Env
from config.yaml is default.
restler <http-command> --env <env-value> <request name>
Fog eg,
restler p -e dev posts
request
flag is useful for seleting individual request from the request collection if you have multiple requests of same http method. Consider following structure:
reslter
requests
posts
- posts.post.yaml
- posts-v2.post.yaml
For running posts-v2, we can use -r
like following:
restler p -r posts-v2 posts
For setting environment variables from response, we can use After
section in request file. For example:
Name: Create Post
URL: "{{API_URL}}"
Method: POST
Headers: ...
Body: ...
After:
Env:
ADDRESS_STREET: Body[address][street]
HOBBIES: Body[hobbies][0]
RESPONSE_DATE: Header[Date]
EMPLOYMENT_START_DATE: Body[employment][details][start_date]
Here, Body
and Header
are special keys for accessing response body and response headers respectively. For accessing, we can use Body[key]
or Header[key]
syntax. If you have array like structure, you can access it using Body[key][index]
or Header[key][index]
. If value is not found, it will write empty string in your env file.
Restler respects the HTTPS_PROXY
and HTTP_PROXY
environment variables. You can specify a proxy URL for individual requests using the R-Proxy-Url
header. To disable the proxy for specific requests, use the R-Proxy-Enable: N
header.
for eg:
Name: Get Posts
URL: "{{API_URL}}"
Method: GET
Headers:
Accept: text/html, application/json
Accept-Encoding: utf-8
R-Proxy-Url: https://something.com:8080
R-Proxy-Enable: N # N or Y, Y is default, if HTTPS_PROXY, HTTP_PROXY or R-Proxy-Url is set
User-Agent: rs-client-0.0.1
Content-Type: application/json
Body:
go build -o restler bin/main.go