Skip to content

Commit e331e6c

Browse files
0hsn0hsn
authored
Merge pull request #38 from chkware/docs/v0.3.4
Docs for v0.3.4
2 parents 20d119f + 8d32202 commit e331e6c

11 files changed

Lines changed: 5096 additions & 5977 deletions

‎docs/00-home.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,18 @@ Read [more value propositions](introduction) here. Find [changelog](https://gith
2424
With [**Python 3.10**](https://www.python.org/downloads/) and [**Pipx**](https://pypa.github.io/pipx/installation/#install-pipx) preinstalled, run following in your terminal to get ***chkware*** installed.
2525

2626
```bash
27-
$ python -m pipx install chk
27+
$ pipx install chk
2828
```
2929

3030
Jump to the [setup guide](setup) for different ways to install ***chkware***.
3131

3232
### Usage
3333

3434
[Get started](quick-start) quickly here.
35-
Find [More examples](examples) here
35+
36+
### Ask anything
37+
38+
Please use tag `chkware-cli` with the question on [stackoverflow.com](https://stackoverflow.com/questions/tagged/chkware-cli) to ask or discuss anything. Follow the tag if you want to help others with your knowledge.
3639

3740
### Contribute
3841

‎docs/02-setup.md‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,19 @@
22
title: Setup
33
---
44

5-
### Installation
5+
## User installation guide
6+
7+
This section describe the process on installation when you intent to use **chkware**.
8+
9+
### chkware toolset installation
610

711

812
The currently supported python version is **_Python 3.10.x_** You need to have this version of python in your OS to continue any of the following steps.
913

1014

1115
**Method 1: with pipx**
1216

13-
The best way to setup any python app is manage it via [pipx](https://pypa.github.io/pipx/). Pipx is a standred pypi python application manager.
17+
The best way to setup any python app is manage it via [pipx](https://pypa.github.io/pipx/). Pipx is a standard pypi python application manager.
1418

1519
First, [Install pipx](https://pypa.github.io/pipx/installation/). Then run
1620

@@ -21,45 +25,60 @@ $ pipx install chk
2125
Then use as following
2226

2327
```bash
24-
$ chk http SomeFile.chk
28+
$ chk http some_file.chk
2529
```
2630

2731
**Method 2: with pip (globally)**
2832

2933
Alternatively you can install with `pip` like other regular python package following these step. However, it will install the package globally.
3034

3135
```bash
32-
$ python3 -m pip install -U pip # upgrade pip
3336
$ python3 -m pip install -U chk
3437
```
3538

3639
Then use as following
3740

3841
```bash
39-
$ python3 -m chk http SomeFile.chk
42+
$ chk http some_file.chk
4043
```
4144

4245
**Method 3: with pip (locally)**
4346

44-
To install under a seperate environment, that don't change your global package space. Install under a virtual env.
47+
To install under a separate environment, that don't change your global package space. You should install under a virtual environment.
4548

4649
```bash
4750
$ python3 -m venv .venv # create virtual environemnt
4851
$ source .venv/bin/activate # active virtual environemnt
49-
$ pip install -U pip # upgrade pip
5052
$ pip install -U chk
5153
```
5254

5355
Then use as following
5456

5557
```bash
58+
$ chk http some_file.chk
59+
```
60+
61+
**Method 4: with pip (locally) from git**
62+
63+
To install latest version or a specific version from source code, under a separate environment, that don't change your global package space. Try following:
64+
65+
```bash
66+
$ python3 -m venv .venv
5667
$ source .venv/bin/activate
57-
$ python -m chk http SomeFile.chk
68+
$ pip install -U https://github.com/chkware/cli/archive/main.tar.gz
5869
```
5970

71+
Then use as following
72+
73+
```bash
74+
$ chk http some_file.chk
75+
```
76+
77+
Read more about this process in [‘pip install’ From a Git Repository](https://adamj.eu/tech/2019/03/11/pip-install-from-a-git-repository/)
78+
6079
---
6180

62-
### Upgrade
81+
### chkware toolset upgrade
6382

6483
If you have installed with **pipx** then use following to upgrade to latest released version.
6584

‎docs/03-quick-start.md‎

Lines changed: 91 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -2,93 +2,100 @@
22
title: Quick Start
33
---
44

5-
To quickly start, let's try something live online.. [REQ|RES](https://reqres.in) is a hosted demo REST api service. Let's call a simple API endpoint from here.
6-
7-
> First [setup **chkware**](setup).
8-
9-
Go to https://reqres.in, and find there is an endpoint like **_GET_ SINGLE USER** we'll call this API with Chkware. So, follow these steps:
10-
11-
1. Create a file called `User.chk`.
12-
2. Put following content
13-
14-
```yaml
15-
---
16-
request:
17-
url: https://reqres.in/api/users/2
18-
method: GET
19-
```
20-
21-
3. from terminal run following
5+
:::note
6+
- **Prerequisite**: First, [setup **chkware**](setup) to continue
7+
- Find [More **`http`** examples](Examples/http-examples) here
8+
:::
9+
10+
Let's call an API that returns current bitcoin price in USD. Please do following:
11+
12+
- Create a file called `bitcoin-usd.chk`
13+
- Open `bitcoin-usd.chk` file, and add following data
14+
15+
```yaml
16+
---
17+
version: default:http:0.7.2
18+
request:
19+
url: https://api.coinstats.app/public/v1/coins/bitcoin?currency=USD
20+
method: GET
21+
```
22+
23+
- Hit enter after writing following command on terminal
24+
25+
```bash
26+
$ chk http bitcoin-usd.chk
27+
```
28+
29+
- You'll get output like following. Data will vary depending on the day you are doing it.
30+
31+
```bash
32+
File: bitcoin-usd.chk
33+
34+
Executing request
35+
36+
- Making request [Success]
37+
====
38+
HTTP/1.1 200 OK
39+
Content-Type: application/json; charset=utf-8
40+
Content-Length: 510
41+
Connection: keep-alive
42+
Date: Sun, 07 Aug 2022 06:05:23 GMT
43+
X-Powered-By: Express
44+
Access-Control-Allow-Origin: *
45+
ETag: W/"1fe-daabae46"
46+
X-Cache: Miss from cloudfront
47+
Via: 1.1 02d36a84a910749e0e01cf16e7e1a02a.cloudfront.net (CloudFront)
48+
X-Amz-Cf-Pop: SIN5-C1
49+
X-Amz-Cf-Id: es7o2_gllNtjITVD3QM3Y5EH3ASHfg1sjav2o5RSSJKH8Mo3Dv_8BA==
50+
51+
{'coin': {'id': 'bitcoin', 'icon': 'https://static.coinstats.app/coins/1650455588819.png', 'name': 'Bitcoin', 'symbol': 'BTC', 'rank': 1, 'price': 22991.80131938709, 'priceBtc': 1, 'volume': 17847616879.01853, 'marketCap': 439482097425.5293, 'availableSupply': 19114731, 'totalSupply': 21000000, 'priceChange1h': 0.11, 'priceChange1d': -0.92, 'priceChange1w': -3.04, 'websiteUrl': 'http://www.bitcoin.org', 'twitterUrl': 'https://twitter.com/bitcoin', 'exp': ['https://blockchair.com/bitcoin/', 'https://btc.com/', 'https://btc.tokenview.com/']}}
52+
```
53+
54+
- Now If you add `--result` flag to the command: it should show you the raw result output.
55+
56+
```bash
57+
$ chk http --result bitcoin-usd.chk
58+
HTTP/1.1 200 OK
59+
Content-Type: application/json; charset=utf-8
60+
Content-Length: 510
61+
Connection: keep-alive
62+
Date: Sun, 07 Aug 2022 06:10:39 GMT
63+
X-Powered-By: Express
64+
Access-Control-Allow-Origin: *
65+
ETag: W/"1fe-779b4c2b"
66+
X-Cache: Miss from cloudfront
67+
Via: 1.1 14193a789201b44415bebb86f9e5fe9c.cloudfront.net (CloudFront)
68+
X-Amz-Cf-Pop: SIN5-C1
69+
X-Amz-Cf-Id: IodB70Lc4gtw_oinJwEIQnzgu9q-HCW_OCVfiAzYUUgmlrJr9CaiGA==
70+
71+
{'coin': {'id': 'bitcoin', 'icon': 'https://static.coinstats.app/coins/1650455588819.png', 'name': 'Bitcoin', 'symbol': 'BTC', 'rank': 1, 'price': 22981.487132414983, 'priceBtc': 1, 'volume': 17816663920.88816, 'marketCap': 439284944516.0738, 'availableSupply': 19114731, 'totalSupply': 21000000, 'priceChange1h': 0.03, 'priceChange1d': -0.9, 'priceChange1w': -3.09, 'websiteUrl': 'http://www.bitcoin.org', 'twitterUrl': 'https://twitter.com/bitcoin', 'exp': ['https://blockchair.com/bitcoin/', 'https://btc.com/', 'https://btc.tokenview.com/']}}
72+
```
73+
74+
- If you open `bitcoin-usd.chk` change like following, you should only get the API response body.
75+
76+
```yaml
77+
---
78+
version: default:http:0.7.2
79+
request:
80+
url: https://api.coinstats.app/public/v1/coins/bitcoin?currency=USD
81+
method: GET
82+
return: .body # <-- to get body of response
83+
```
84+
85+
```bash
86+
$ chk http --result bitcoin-usd.chk
87+
{'coin': {'id': 'bitcoin', 'icon': 'https://static.coinstats.app/coins/1650455588819.png', 'name': 'Bitcoin', 'symbol': 'BTC', 'rank': 1, 'price': 22981.487132414983, 'priceBtc': 1, 'volume': 17816663920.88816, 'marketCap': 439284944516.0738, 'availableSupply': 19114731, 'totalSupply': 21000000, 'priceChange1h': 0.03, 'priceChange1d': -0.9, 'priceChange1w': -3.09, 'websiteUrl': 'http://www.bitcoin.org', 'twitterUrl': 'https://twitter.com/bitcoin', 'exp': ['https://blockchair.com/bitcoin/', 'https://btc.com/', 'https://btc.tokenview.com/']}}
88+
```
89+
90+
- now we will use `jq` json parser to get price data. [jq website](https://stedolan.github.io/jq/) here.
2291

2392
```bash
24-
$ chk http User.chk
25-
```
26-
27-
See the output like
28-
29-
```text
30-
HTTP/1.1 200 OK
31-
Date: Sat, 29 Jan 2022 16:46:26 GMT
32-
Content-Type: application/json; charset=utf-8
33-
Transfer-Encoding: chunked
34-
...truncated-headers...
35-
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400
36-
37-
{'data': {'id': 2, 'email': 'janet.weaver@reqres.in', 'first_name': 'Janet', 'last_name': 'Weaver', 'avatar': 'https://reqres.in/img/faces/2-image.jpg'}, 'support': {'url': 'https://reqres.in/#support-heading', 'text': 'To keep ReqRes free, contributions towards server costs are appreciated!'}}
38-
```
39-
40-
:wink::tada::confetti_ball:
41-
93+
$ chk http --result bitcoin-usd.chk | jq '.coin.price'
94+
22981.487132414983 # <-- depends on the current value
95+
```
4296
---
97+
We just fetched a live API. You can use `chk http` as your scriptable http client like this :rocket::star2:.
4398

44-
Now let's try a more complex API. Let's call COVID-19 data from RapidAPI. You can call this api for any country with a two letter country code. Let's do the following to fetch covid-19 data for Bangladesh:
45-
46-
1. Register or login to https://rapidapi.com
47-
2. Subscribe to https://rapidapi.com/Gramzivi/api/covid-19-data/ this source.
48-
3. Create a directory called `~/project` and `covid-19.chk` in it
49-
4. Now open `covid-19.chk` file and add following data
50-
51-
```yaml
52-
---
53-
request:
54-
url: https://covid-19-data.p.rapidapi.com/report/country/code
55-
url_params:
56-
code: bd
57-
date: '2020-04-01'
58-
method: GET
59-
headers:
60-
X-RapidAPI-Host: 'covid-19-data.p.rapidapi.com'
61-
X-RapidAPI-Key: '<your X-RapidAPI-Key>'
62-
```
63-
64-
1. hit enter writing following command on terminal
65-
66-
```bash
67-
$ cd ~/project
68-
$ chk http covid-19.chk
69-
```
70-
71-
1. You'll get output like this
72-
73-
```text
74-
HTTP/1.1 200 OK
75-
Cache-Control: no-cache, private
76-
Content-Type: application/json
77-
Date: Sun, 23 Jan 2022 04:28:35 GMT
78-
ETag: "69236d0ee4cbd7e37314028f0a8b01be"
79-
Server: RapidAPI-1.2.8
80-
Vary: Accept
81-
X-RapidAPI-Region: AWS - ap-southeast-1
82-
X-RapidAPI-Version: 1.2.8
83-
X-RateLimit-Requests-Limit: 50000
84-
X-RateLimit-Requests-Remaining: 49988
85-
X-RateLimit-Requests-Reset: 2175151
86-
Content-Length: 182
87-
Connection: keep-alive
88-
89-
[{'country': 'Bangladesh', 'provinces': [{'province': 'Bangladesh', 'confirmed': 54, 'recovered': 25, 'deaths': 6, 'active': 23}], 'latitude': 23.684994, 'longitude': 90.356331, 'date': '2020-04-01'}]
90-
```
99+
Going further, you should save these `.chk` files in git repo, so that you can run it later, from anywhere where **chkware** is installed. Cheers.
91100

92101
:wink::tada::confetti_ball:
93-
94-
You just fetch a live API. Going further, you should save these `.chk` files in git repo, so that you can run it later, from anywhere where **chkware** is installed. Cheers.

0 commit comments

Comments
 (0)