# apicall - User-friendly RESTful API & JSON-RPC Client
Apicall is a useful API client. It will realize easy to calling API compared to the curl command in 90% of use case.
## Features
- **URL prefix omission**:
You can omit some URL components like schema, hostname, part of path.
- **Git integration**:
The apicall locates a configuration file on the git root directory. So settings will change for each git repositories.
- **Formatted and colored JSON response**:
All JSON response is formatted and colored by the jq command by default. You can reduce of work of reading minified
JSON.
- **Useful query string builder**:
Remaining positional arguments of the `restcall` command regard as key-value pairs of query string parameters. Keys
and values applies URL escape. So you don't need to assemble of URL-encoded query string. See the usage section and
the tutorial section for detail.
- **Default authentication headers**:
The apicall sets authentication headers on all requests if header setting exists. You can easily call APIs that
require an authentication token.
- **Automatic endpoint discovery**:
If the endpoint is not specified, the apicall discovers famous HTTP ports in the localhost and tries to request.
- **Binary safe**:
The apicall converts response in hex representation when writing binary response into a terminal.
## Usage
```bash
$ apicall endpoint https://example.com/rest-api/v1
$ restcall post /users -d '{"name": "bob"}'
$ restcall get /users/10
$ restcall get /users/search 'name=bob'
$ restcall delete /users/10
$ restcall get https://example.com/api
$ apicall endpoint https://example.com/json-rpc/v1
$ jsonrpccall create_account 'bob'
$ jsonrpccall get_account 10
$ jsonrpccall search_accounts_by_name 'bob'
$ jsonrpccall delete_account 10
```
## Requirements
* Python 3.7 or later
* [jq command](https://stedolan.github.io/jq/)
* [yapf command](https://github.com/google/yapf) (For development)
* [mypy command](http://mypy-lang.org/) (For development)
* [py.test](https://docs.pytest.org/en/latest/) (For development)
## Installation
_NOTE: If you want develop the apicall, see the "Development" section._
Please run the following command.
```bash
$ python3 -m pip install apicall # Install stable version from pypi.
or
$ python3 -m pip install git+https://github.com/yuuki0xff/apicall # Install latest version from github.
$ sudo apt install jq # Debian, Ubuntu
$ brew install jq # Mac
```
## Tutorial
The `apicall` provides all features in a command. Also, some alias commands exist. The original command name is too
long. We recommend that you use alias commands.
```
restcall # The alias command of `apicall rest`.
jsonrpccall # The alias command of `apicall jsonrpc`.
```
Before calling API, you should check the setting of the apicall. Most important is endpoint setting. It displays and
changes by `apicall endpoint` command. When multiple endpoints are specified, the apicall tries sending a request to
the first destination. If connection error occurred, it tries sending a request to the second destination. The
default endpoint setting is localhost addresses with some famous HTTP ports like http://localhost:8080,
http://localhost:3000, and so on. So if you need to send requests to the local development server, you can use it
without setting changes.
```bash
# Show endpoints.
apicall endpoint
# Set endpoint.
apicall endpoint http://localhost:8080/api/v1
```
The apicall setting is complete. Let send requests to the server.
```bash
# Send a GET request to http://localhost:8080/api/v1/users.
# Command syntax: restcall METHOD URL [QUERY_STRING ...]
restcall get /users
# Same as above.
restcall get users
# With query string.
# http://localhost:8080/users?name=alice&age=%3E20
restcall get /users name=alice 'age=>20'
# With complex query string.
# http://localhost:8080/items?q=bulk%20%22apple%20juice%22
restcall get /items 'q=bulk "apple juice"'
# Of course, you can send a request without using the query string builder.
restcall get '/items?q=bulk+%22apple+juice%22'
# You can also use both the hand-assembled query string and the query string builder.
# http://localhost:8080/items?q=bulk+%22apple+juice%22&sort=price&order=asc
restcall get '/items?q=bulk+%22apple+juice%22' sort=price order=asc
# Send a DELETE request.
restcall delete /items/25
# Send a POST request. The content type is automatically detected and implicitly added to request headers. You can
# override this value by the --type option.
restcall post /user/alice -d '{"age":28, "email": "alice@example.com"}'
restcall post /user/alice/message -d 'Hello!'
restcall post /user/alice/icon -d @./Pictures/my-icon.jpg --type image/jpeg
# When the server sends a binary response... Don't worry! The apicall converts response in hex representation.
restcall get https://github.com/favicon.ico
# If stdout is not terminal, the apicall doesn't convert response. So you can save original binary data to the file.
restcall get https://github.com/favicon.ico >favicon.ico
# If the -v option specified, you can see request/response headers.
restcall get /users -v
```
## Quick reference
```
apicall auth header
apicall auth header set NAME VALUE
apicall auth header unset NAME ...
apicall auth basic
apicall auth basic set USER PASSWORD
apicall auth basic unset
apicall endpoint [URLS ...]
restcall METHOD URL [QUERIES ...]
jsonrpccall FUNC [ARGS ...]
```
## Development
Please run the following commands.
When install succeed, apicall commands are installed to your computer.
If you edited some codes under the git repository, changes are applied immediately to the behavior of apicall command.
```bash
$ git clone https://github.com/yuuki0xff/apicall
$ cd apicall
$ python3 -m pip install -e '.[dev]'
```
## TODO
* Improve help messages and documentation.
* Support gRPC protocol.
Raw data
{
"_id": null,
"home_page": "https://github.com/yuuki0xff/apicall",
"name": "apicall",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "development rest api json-rpc http client",
"author": "The Python Packaging Authority",
"author_email": "yuuki0xff@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c2/a1/88d5f2f26b53680e6409df75bc57b2b954beb81181eca8ddfdf235747eb0/apicall-0.2.0.tar.gz",
"platform": null,
"description": "# apicall - User-friendly RESTful API & JSON-RPC Client\n\nApicall is a useful API client. It will realize easy to calling API compared to the curl command in 90% of use case.\n\n\n## Features\n- **URL prefix omission**: \n You can omit some URL components like schema, hostname, part of path.\n- **Git integration**: \n The apicall locates a configuration file on the git root directory. So settings will change for each git repositories.\n- **Formatted and colored JSON response**: \n All JSON response is formatted and colored by the jq command by default. You can reduce of work of reading minified\n JSON.\n- **Useful query string builder**: \n Remaining positional arguments of the `restcall` command regard as key-value pairs of query string parameters. Keys\n and values applies URL escape. So you don't need to assemble of URL-encoded query string. See the usage section and\n the tutorial section for detail.\n- **Default authentication headers**: \n The apicall sets authentication headers on all requests if header setting exists. You can easily call APIs that\n require an authentication token.\n- **Automatic endpoint discovery**: \n If the endpoint is not specified, the apicall discovers famous HTTP ports in the localhost and tries to request.\n- **Binary safe**: \n The apicall converts response in hex representation when writing binary response into a terminal.\n\n\n## Usage\n```bash\n$ apicall endpoint https://example.com/rest-api/v1\n$ restcall post /users -d '{\"name\": \"bob\"}'\n$ restcall get /users/10\n$ restcall get /users/search 'name=bob'\n$ restcall delete /users/10\n$ restcall get https://example.com/api\n\n$ apicall endpoint https://example.com/json-rpc/v1\n$ jsonrpccall create_account 'bob'\n$ jsonrpccall get_account 10\n$ jsonrpccall search_accounts_by_name 'bob'\n$ jsonrpccall delete_account 10\n```\n\n\n## Requirements\n* Python 3.7 or later\n* [jq command](https://stedolan.github.io/jq/)\n* [yapf command](https://github.com/google/yapf) (For development)\n* [mypy command](http://mypy-lang.org/) (For development)\n* [py.test](https://docs.pytest.org/en/latest/) (For development)\n\n\n## Installation\n_NOTE: If you want develop the apicall, see the \"Development\" section._\n\nPlease run the following command.\n\n```bash\n$ python3 -m pip install apicall # Install stable version from pypi.\n or\n$ python3 -m pip install git+https://github.com/yuuki0xff/apicall # Install latest version from github.\n\n$ sudo apt install jq # Debian, Ubuntu\n$ brew install jq # Mac\n```\n\n\n## Tutorial\nThe `apicall` provides all features in a command. Also, some alias commands exist. The original command name is too\nlong. We recommend that you use alias commands.\n\n```\nrestcall # The alias command of `apicall rest`.\njsonrpccall # The alias command of `apicall jsonrpc`.\n```\n\nBefore calling API, you should check the setting of the apicall. Most important is endpoint setting. It displays and\nchanges by `apicall endpoint` command. When multiple endpoints are specified, the apicall tries sending a request to\nthe first destination. If connection error occurred, it tries sending a request to the second destination. The\ndefault endpoint setting is localhost addresses with some famous HTTP ports like http://localhost:8080,\nhttp://localhost:3000, and so on. So if you need to send requests to the local development server, you can use it\nwithout setting changes. \n\n```bash\n# Show endpoints.\napicall endpoint\n# Set endpoint.\napicall endpoint http://localhost:8080/api/v1\n```\n\nThe apicall setting is complete. Let send requests to the server.\n\n```bash\n# Send a GET request to http://localhost:8080/api/v1/users.\n# Command syntax: restcall METHOD URL [QUERY_STRING ...]\nrestcall get /users\n# Same as above.\nrestcall get users\n\n# With query string.\n# http://localhost:8080/users?name=alice&age=%3E20\nrestcall get /users name=alice 'age=>20'\n\n# With complex query string.\n# http://localhost:8080/items?q=bulk%20%22apple%20juice%22\nrestcall get /items 'q=bulk \"apple juice\"'\n# Of course, you can send a request without using the query string builder.\nrestcall get '/items?q=bulk+%22apple+juice%22'\n# You can also use both the hand-assembled query string and the query string builder.\n# http://localhost:8080/items?q=bulk+%22apple+juice%22&sort=price&order=asc\nrestcall get '/items?q=bulk+%22apple+juice%22' sort=price order=asc\n\n# Send a DELETE request.\nrestcall delete /items/25\n\n# Send a POST request. The content type is automatically detected and implicitly added to request headers. You can\n# override this value by the --type option.\nrestcall post /user/alice -d '{\"age\":28, \"email\": \"alice@example.com\"}'\nrestcall post /user/alice/message -d 'Hello!'\nrestcall post /user/alice/icon -d @./Pictures/my-icon.jpg --type image/jpeg\n\n# When the server sends a binary response... Don't worry! The apicall converts response in hex representation.\nrestcall get https://github.com/favicon.ico\n# If stdout is not terminal, the apicall doesn't convert response. So you can save original binary data to the file.\nrestcall get https://github.com/favicon.ico >favicon.ico\n\n# If the -v option specified, you can see request/response headers.\nrestcall get /users -v\n```\n\n\n## Quick reference\n```\napicall auth header\napicall auth header set NAME VALUE\napicall auth header unset NAME ...\napicall auth basic\napicall auth basic set USER PASSWORD\napicall auth basic unset\napicall endpoint [URLS ...]\n\nrestcall METHOD URL [QUERIES ...]\njsonrpccall FUNC [ARGS ...]\n```\n\n\n## Development\nPlease run the following commands.\nWhen install succeed, apicall commands are installed to your computer.\nIf you edited some codes under the git repository, changes are applied immediately to the behavior of apicall command.\n\n```bash\n$ git clone https://github.com/yuuki0xff/apicall\n$ cd apicall\n$ python3 -m pip install -e '.[dev]'\n```\n\n## TODO\n* Improve help messages and documentation.\n* Support gRPC protocol.\n",
"bugtrack_url": null,
"license": null,
"summary": "User-friendly RESTful API & JSON-RPC Client",
"version": "0.2.0",
"project_urls": {
"Bug Reports": "https://github.com/yuuki0xff/apicall/issues",
"Homepage": "https://github.com/yuuki0xff/apicall",
"Source": "https://github.com/yuuki0xff/apicall"
},
"split_keywords": [
"development",
"rest",
"api",
"json-rpc",
"http",
"client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2aaef5cb962b5e456a944434b0aa599e8ecf556882a853208f05260dd3b41116",
"md5": "90f3e54481ce3b39a73a15374c04b8a5",
"sha256": "9c7d63c2d9575e4b39bb4513562729d22265729f333832db6d88f43ed674d38e"
},
"downloads": -1,
"filename": "apicall-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90f3e54481ce3b39a73a15374c04b8a5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14840,
"upload_time": "2025-08-03T16:48:56",
"upload_time_iso_8601": "2025-08-03T16:48:56.053357Z",
"url": "https://files.pythonhosted.org/packages/2a/ae/f5cb962b5e456a944434b0aa599e8ecf556882a853208f05260dd3b41116/apicall-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c2a188d5f2f26b53680e6409df75bc57b2b954beb81181eca8ddfdf235747eb0",
"md5": "10f689f22e5b9e13d240a71bf682ac2b",
"sha256": "03a1505677ed91db1ffb9e14f637662f4bbecb7ab492ac7c251f5ee864f3af9b"
},
"downloads": -1,
"filename": "apicall-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "10f689f22e5b9e13d240a71bf682ac2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19702,
"upload_time": "2025-08-03T16:48:57",
"upload_time_iso_8601": "2025-08-03T16:48:57.464811Z",
"url": "https://files.pythonhosted.org/packages/c2/a1/88d5f2f26b53680e6409df75bc57b2b954beb81181eca8ddfdf235747eb0/apicall-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 16:48:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yuuki0xff",
"github_project": "apicall",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "apicall"
}
JSON
