rc = REST CLI
rc is a tool to help execute REST API requests.
rc is based on Collections, Environments and Requests. Similar to the tool we all love/hate --- Postman.
- A Collection is a local directory (optionally checked in as a git repository somewhere).
- A Collection contains *.request files that each represent a single REST API Request that can be executed
- The output from executing a *.request file is normally:
- The HTTP response body to standard out
- A detailed *.response file saved in the same directory as the *.request file sent
rc is installed as a Python script. The instructions below should work fine for most users. Please reach out if they don't. The MacOS instructions leverage "pipx" to install in a Python virtualenv instead of with your system Python modules.
If you'd like to install with "pipx" in Windows that works fine as well, but is not documented here. See: https://github.com/pypa/pipx
- Pre-reqs
- Python 3.12+ (required)
- VSCode (optional, but highly recommended)
- Windows:
- Install
- pip install rc3
- Upgrade
- pip install --upgrade rc3
- Windows Troubleshooting
- See: Windows Setup Issues
- Install
- MacOS
- Pre-reqs
- brew install python
- brew install pipx
- pipx ensurepath
- Install
- pipx install rc3
- Upgrade
- pipx upgrade rc3
- Pre-reqs
- First create an empty directory somewhere (any name & location is fine)
$ mkdir temp-collection $ cd temp-collection - Next run "rc new" to create a new collection
- Choose all default values, and you'll get an example collection you can explore
$ rc new Enter a NAME for this COLLECTION [temp-collection]: Include example Requests in your new collection? [Y/n]: Importing collection into RC_HOME/rc-settings.json Collection 'temp-collection' has been successfully imported, try 'rc list' next... - Next run "rc list" to see what's in the example collection you just created
$ rc list Listing COLLECTIONS found in settings.json: NUM: NAME: LOCATION: 1 example-rc C:\git\example-rc 2* temp-collection C:\temp-collection Listing ENVIRONMENTS found in current_collection: NUM: NAME: baseUrl: 1* dev https://greetings-mvrsygo3gq-uc.a.run.app 2 localhost http://localhost:8080 Listing REQUESTS found in current_collection: NUM: FOLDER: METHOD: NAME: 1* /greetings-basic GET greeting 2 /greetings-basic GET greetings 3 /greetings-basic POST new-greeting 4 /greetings-basic DELETE remove-greeting 5 /greetings-basic PUT update-greeting 6 /greetings-oauth2 GET greeting 7 /greetings-oauth2 POST mint-admin-token 8 /greetings-oauth2 POST mint-token - Next send the "greeting" request with the rc send command
- Wait for it…
- A greetings-demo project is running on Google Cloud Run
- And it scales down to 0 instances when there is no demand (i.e. your first few requests will be SLOW…)
$ rc send greeting { "id": 1, "text": "Hello", "language": "English" } - Wait for it…
- Next "cat" the generated greeting.response file that will have more verbose output from the send command
$ cat greetings-basic/greeting.response { "status_code": 200, "time": "845.772ms", "size": { "body": 44, "headers": 442, "total": 486 }, "headers": { "vary": "Origin,Access-Control-Request-Method,Access-Control-Request-Headers", "Date": "Wed, 08 May 2024 15:06:54 GMT", "Server": "Google Frontend", ... }
- All the requests in the example collection can be sent to the greetings-demo app running on Google Cloud Run
- To view all requests in the example collection run "rc request --list"
$ rc request --list Listing REQUESTS found in current_collection: NUM: FOLDER: METHOD: NAME: 1* /greetings-basic GET greeting 2 /greetings-basic GET greetings 3 /greetings-basic POST new-greeting 4 /greetings-basic DELETE remove-greeting 5 /greetings-basic PUT update-greeting 6 /greetings-oauth2 GET greeting 7 /greetings-oauth2 POST mint-admin-token 8 /greetings-oauth2 POST mint-token - Try sending requests by NUMBER instead of by NAME using these commands:
$ rc send 1 $ rc send 2 $ rc send 3 - Notes:
- Make sure there is a greeting #8 before sending request 4, or you'll get a 404
- Make sure you run request 7, before request 6, so you have a {{ token }} available in your global environment
- View all Collections, Environments, and Requests you have setup on this machine
- rc list
- View all Requests for the current Collection (the following commands are equivalent):
- rc list requests
- rc list r
- rc r
- Pick a new active request in the current collection (the following commands are equivalent):
- rc request --pick new-greeting
- rc request --pick 3
- rc request 3
- rc r 3
- View the definition of the active request:
- rc request --info
- rc r --info
- rc r -i
- Send the current request (what you just picked)
- rc send
- Edit the current request & send it UPON file close
- rc send --edit
- Pick a new current request from a list & send it immediately
- rc send --pick
- Pick a new current request (WITHOUT a list/prompt) & send it immediately
- rc send --pick 7
- A common pattern might be to:
- save a GET response
- edit the JSON/response locally
- then PUT/POST back to save or create a new record
- The "--file" option on the "rc send" command supports this flow
- When the "--file" option is used you must pass a filename with the option
- The contents of that filename will be used as the BODY of the request (overriding what's in the .request template)
- An example below using the example collection; uses a GET response as a template for a new POST request.
$ rc send greeting > my.json $ vi my.json $ rc send new-greeting --file my.json { "id": 6, "text": "Koar", "language": "Martian" } - The "--file" option follows the convention of a "-" character for the filename represents STDIN
- Using this feature you can pipe the output of 1 request into another, example below
$ rc send greeting | rc send new-greeting --file - { "id": 7, "text": "Hello", "language": "English" } - If you wish to have file contents just override a portion of your .request template & not replace the entire BODY
- see the #file helper function in the additional help document Helper Functions
- For documentation on some more niche CLI commands See: Additional Commands
- rc upgrade --- upgrades schemas & files in your collection
- rc decode --- decodes/displays JWTs in your environment
- rc keyring --- get/set/delete values in your OS keyring (Keychain, or Win Cred Locker)
- View overall help and a list of all available sub-commands
- rc
- View help for specific sub-commands
- rc request --help
- rc collection --help
- rc environment --help
- The example collection you created with the "rc new" command is also checked into a git repository here:
- https://github.com/gswilcox01/example-rc
- You can clone & import collections following the example below:
$ git clone https://github.com/gswilcox01/example-rc.git Cloning into 'example-rc'... remote: Enumerating objects: 33, done. remote: Counting objects: 100% (33/33), done. remote: Compressing objects: 100% (17/17), done. remote: Total 33 (delta 14), reused 33 (delta 14), pack-reused 0 Receiving objects: 100% (33/33), 4.87 KiB | 262.00 KiB/s, done. Resolving deltas: 100% (14/14), done. $ cd example-rc $ rc import Importing collection into RC_HOME/rc-settings.json Collection 'example-rc' has been successfully imported, try 'rc list' next...
- Authentication can be defined in a Request, Folder, or in the collection.json file in the root of your collection
- Inheritance is walked until auth is defined, or the root of the collection is found in this order:
- request > folder > parent folder > collection.json
- For examples of authentication see the following files in the example collection:
- /greetings-basic/folder.json
- /greetings-basic/greeting.request
- /greetings-oauth2/mint-admin-token.request
- /examples/example_Auth_Basic.request
- /examples/example_Auth_Bearer.request
- /examples/example_Auth_Token.request
- Similar to postman, env vars in handlebars will be replaced in request files before being sent.
- Example handlebar format:
- {{ var_name }}
- Environments are searched in the following order for values:
- Current environment in collection
- Global environment in RC_HOME
- SHELL/OS ENVIRONMENT
- Keyring values (MacOS Keychain, Windows Cred Locker)
- For more info see "keyring" command here: Additional Commands
- For examples of variable placeholders, see the following files in the example collection:
- /greetings-basic/rc-folder.json
- /greetings-oauth2/mint-admin-token.request
- Helper functions are similar to env var substitution, in that they use handlebar expressions that get replaced in your template
- A simple example is the #uuid helper function, which replaces the expression with a UUID
- {{ #uuid }}
- For more complete documentation on helper functions see: Helper Functions
- #uuid --- generates a new Type4 UUID
- #pkce_cvcc --- generates a PKCE code_verifier & code_challenge
- #prompt --- will prompt the user for input
- #secure_prompt --- will prompt the user for input (that is masked on screen)
- #keyring_prompt --- will read a value from your OS keyring, or secure prompt for a value
- #keyring --- will read a value from your OS keyring (Keychain or Win Cred Locker)
- #file --- will inject '--file' option file contents into just a portion of your template
- You can extract a value from any response and save it into the current or global Environment
- You can extract with either of:
- JsonPath (preferred)
- Python Regex
- For an example of each see the following files in the example collection:
- /examples/example_Extract_JsonPath.request
- /examples/example_Extract_Regex.request
- For an example of using multiple extracts on 1 request, and various "to" and "from" options see:
- /examples/example_KitchenSink.request
- Extract "from" options:
- "body" --- will extract from the BODY of the response (this is the default)
- "response" --- will extract from the verbose output saved to .response file
- Extract "to" options:
- "current" --- will extract to the currently selected env
- "global" --- will extract to the global env (this is the default)
- "stdout" --- will replace the normal stdout, to just the extracted value(s)
- "response" --- will extract to the verbose .response file that is generated
- Read more about Json Path here:
- Read more about Python Regex here:
- Settings are mostly only documented in the default settings.json file & the settings schema
- See: https://json.schemastore.org/rc3-settings-0.0.3.json
- Or after running "rc" for the first time see:
- RC_HOME/rc-settings.json
- rc leverages Python Requests defaults which honors these ENV VARS for proxy settings:
- HTTP_PROXY
- HTTPS_PROXY
- NO_PROXY
- ALL_PROXY
- NO_PROXY/Proxy Bypass:
- Note: IP addresses are not allowed/honored, and hostnames must be used
- See: psf/requests#4871
- See more info about Python Requests Proxies here:
- By default rc will follow Python Requests default behaviour
- Using the Python 'certifi' module truststore file
- And verifying certs
- You can turn off cert verification in RC_HOME/settings.json with:
- "ca_cert_verification": false,
- You can set a custom cert ca_bundle file in RC_HOME/settings.json with:
- "ca_bundle": "/path/to/ca/bundlefile",
- You can alternatively set the path to a ca_bundle file with one of these ENV VARS:
- REQUESTS_CA_BUNDLE
- CURL_CA_BUNDLE
- For more details see:
- Associate *.request & *.response files with the JSON editor
- Open a file that needs mapping
- CTRL + SHIFT + P
- Choose "Change Language Mode"
- Choose "Configure File Association for '.extension'"
- Choose "JSON" from the list