RAT - the Rest Api Tool

Rat is a simple command line tool that helps me automate repetitive tasks for my favorite web services and software products which expose a REST API. The general guideline for all commands rat supports is that they should perform only one thing preferably with one HTTP call only. This guideline follows the UNIX principle that tools should do one thing and complex behaviour is achieved by pipelining.

Table of Contents

• Available Clients
• Installation
  • macOS
  • Ubuntu
  • Windows
  • From Source
• Usage
  • General
  • CenterDevice
    • Authenticate rat
    • Refresh access token
    • Search collection
    • Download document
    • Search document
    • Upload document
    • Delete document
  • Pocket
    • Authentication
      • Create a consumer key
      • Authenticate rat
    • Archive | Readd | Favorite | Unfavorite | Delete
    • List and Search
      • Advanced listing
  • Slack
    • Authentication
      • Create client ID and client Secret
      • Authenticate rat
  • Stocks
    • Scrape current stock price from comdirect web page
• Clients to Come
• Todos
• References
  • Pocket
  • Rust
• Crates
• Credits

Available Clients

CenterDevice

rat centerdevice auth
rat centerdevice collections
rat centerdevice delete
rat centerdevice download
rat centerdevice refresh_token
rat centerdevice search
rat centerdevice status
rat centerdevice upload

Pocket

rat pocket auth
rat pocket list
rat pocket archive
rat pocket readd
rat pocket favorite
rat pocket unfavorite
rat pocket delete

Slack

rat slack auth

Stocks

rat stocks

Installation

macOS

Please use Homebrew to install rat on your system.

brew install lukaspustina/os/rat

Ubuntu

Pleae add my [PackageCloud] open source repository and install rat via apt.

curl -s https://packagecloud.io/install/repositories/lukaspustina/opensource/script.deb.sh | sudo bash
sudo apt-get install rat

Windows

rat is automatically build on Windows via AppVeyor to ensure is compiles and runs fine but binaries are currently not provided. Please compile it from source.

From Source

Please install Rust via rustup and then run

cargo install rat

Usage

General

There are two response output modes, i.e., JSON and HUMAN, and three message levels, i.e., QUIET, NORMAL, and VERBOSE.

In human output mode tries to give a concise representation if the received information. In json output mode, rat tries to pass the whole json response to the user -- if any is available. The output mode can be selected with the parameter --output <humen|json>, e.g., rat --output json ...

The message output levels configure how talkative rat is during execution. The quiet level reduces outputs to real responses only while the normal level tries to give some feedback to the user about the start and end of a request. The verbose level goes one step further and tries to inform the user about each step of the processing. The message level can be chosen with the parameters --quiet or --verbose, respectively. If none of these switches is activated, the message level is set to normal. For example, rat --verbose ... selects the verbose message level.

CenterDevice

Authenticate rat

rat centerdevice auth and follow the instructions.

Refresh access token

rat centerdevice refresh_token

Search collection

• Show my collections: rat centerdevice collections

• Show my as well as public collections: rat centerdevice collections --public-collections

• Search collections: rat centerdevice collections <search filter>

• Cache collection names for other commands: rat centerdevice collections --cache

Download document

• Download document into current directory with original filename: rat centerdevice download excbd68a-c397-id46-9350-a4fd4022fe8c

• Download document with new filename: rat centerdevice download excbd68a-c397-id46-9350-a4fd4022fe8c -f new_filename

Search document

• Search for documents with filename README.md, tagged with documentation, and some fulltext: rat centerdevice search -f README.md -t documentation -t rat "the Rest Api Tool"

• Search again, but now post-process JSON response with jq: rat --output json --quiet centerdevice search -f README.md -t documentation "the Rest Api Tool" | jq .

• Expand search to public collections: ... --public-collections

Upload document

• Upload documen with tags: rat centerdevice upload README.md -t documentation -t rat

• Upload document to collection: rat centerdevice upload README.md --collection <collection id>

• Upload document to collection using collection cache: rat centerdevice upload README.md --Collection <cached collection name>

Delete document

rat centerdevice delete excbd68a-c397-id46-9350-a4fd4022fe8c

Pocket

Authentication

Create a consumer key

Create a new application and add the newly created consumer key to your rat configuration, section [pocket] as consumer_key = '<consumer key'.

Authenticate rat

rat pocket auth and follow the instructions.

Archive | Readd | Favorite | Unfavorite | Delete

rat pocket archive|readd|favorite|unfavorite|delete <article ids>...

List and Search

Search in title and URL of all articles ...

• the word rust: rat pocket list rust

List all ...

• unread articeles: rat pocket list

• archived articeles: rat pocket list --state archived

• articles: rat pocket list --state all

• unread articles tagged with Rust: rat pocket list --tag Rust

• unread articles, added between 2 weeks and 1 week ago: rat pocket list --since 2w --until 1w

• List ids of all unread articles added 2 weeks or later ago and create a comma separated list: rat pocket list --until 2w --output id | paste -s -d . -

Advanced listing

• List all unread articles that contain a video: rat --output json --quiet pocket list | jq '.list | .[] | select(.has_video | test("1") ) | { id: .item_id, title: .resolved_title }'

• Filter articles that contain Rust in title and URL, and create comma separated id list: rat -o json --quiet pocket list | jq -r '.list | .[] | { title: .given_title, id: .item_id, url: .given_url } | select((.title | test("Rust")) or (.url | test("Rust"))) | .id' | paste -s -d , -

Slack

Authentication

Create client ID and client Secret

Create a new application and add the newly created Client ID and Client Secret to your rat configuration, section [slack] as client_id = '<client id>' and client_secret = '<client secret', respectively.

Authenticate rat

rat slack auth and follow the instructions.

Stocks

Scrape current stock price from comdirect web page

• by company name: rat stocks "Comdirect"

• by WKN: rat stocks 542800"

---

Clients to Come

rat feedly

rat elasticsearch browse
rat elasticsearch status -- curl -s http://<host>:9200/_cluster/health?level=shards
rat elasticsearch health -- curl -s http://<host>:9200/_cluster/health

rat slack channel list
rat slack user list
rat slack send <channel|user> <message>

rat bosun browse
rat bosun incidents show --open
rat bosun incidents ack|close --ids  <id>,<id> --message "Just because ..."
rat bosun show-silences
rat bosun silence show
rat bosun silence set

Todos

• Clap

  • bash and zsh autocompletion

• Fill out Cargo.toml

• Error Chain

• Distributions

  • Brew

  • Debian

• Finish Pocket

• Output

  • General option

  • colors: regular, info(blue), warnings(yellow), error(red)

  • add info msgs to modules

  • quiet option

  • Add output format parameter

  • Apply output format to all, well, outputs

• Slack Auth

• CenterDevice Auth

• CenterDevice Upload

  • Use streams

• Checkout mime_multipart 0.5 with my patch included

• Move centerdevice browse-status to status --browse

• Enchance Auths by --browser which opens a browser window.

• Enhance Pocket

  • Add --since and --until parameters for search

  • Select human outout fields: id, title, url

  • Update documentation

• Refactor auth modules - cf. branch

• Slack: Move HTTP calls to client mod

• Replace curl with hyper

• Pocket: Move HTTP calls to client mod

• Replace Pocket list and search by search that optionally takes a search term

• Travis

  • packagecloud.io

  • Add Badges for Travis in Cargo.toml and Readme

• Wait for new select release and then let Travis publish to crates.io

• CenterDevice

  • Refactor client lib

  • search for collections

  • upload to collection

  • named collections

  • upload to named collections

  • delete document

  • Token Refresh / Error messages when token has expired

• Elastic tabstops for output where appropriate

  • pocket list -- but not everywhere

• Tests

• Make better use of error_chain

  • by using Foreign errors

  • by using ensure!

• Dockerize runs for better backtraces

  docker run -v $PWD:/volume -w /volume -t clux/muslrust:nightly sh -c "cargo run"

• Run Clippy once cargo in nightly works again -- cf. http://asquera.de/blog/2017-03-03/setting-up-a-rust-devenv/

• Move to future based clients -- cf. http://asquera.de/blog/2017-03-01/the-future-with-futures/

-- Before first 1.0 release

• Documentation

  • Add documentation generation to .travis

• Cleanup of Readme; esp. Todos

---

References

Pocket

• Pocket API

• Pocket Auth

Rust

• Rust and Rest

• Starting a new Rust project right, with error-chain

Crates

• elastic tabstops

• serde

• Testing

  • Discussion of frameworks

  • Common Pattern for test setups, also see this

  #[test]
  fn make_sure_foo_works() {
      setup(|&fixture_state| { ... });
  }

  • BDD

    • Stainless

    • rspec

  • spectral

  • Quickcheck

  • Mocks

Credits

• Rat icon is (C) by Eduardo Gonçalves Costa under CC BY 3.0 US.