ipify-rs 0.7.0

Rust crate for the ipify.org API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

<!-- omit in TOC -->

# ipify-rs

> **Rust API & CLI for accessing the ipify.org HTTP API**

[![Cirrus-CI](https://api.cirrus-ci.com/github/keltia/ipify-rs.svg?branch=main)](https://cirrus-ci.org/keltia/ipify-rs)
[![Build status](https://github.com/keltia/ipify-rs/actions/workflows/rust.yml/badge.svg)](https://github.com/keltia/ipify-rs/actions/workflows/rust.yml)
[![Build status (develop)](https://github.com/keltia/ipify-rs/actions/workflows/develop.yml/badge.svg)](https://github.com/keltia/ipify-rs/actions/workflows/develop.yml)
[![Crates.io](https://img.shields.io/crates/v/ipify-rs.svg)](https://crates.io/crates/ipify-rs)
[![Docs](https://docs.rs/ipify-rs/badge.svg)](https://docs.rs/ipify-rs)
[![GitHub release](https://img.shields.io/github/release/keltia/ipify-rs.svg)](https://github.com/keltia/ipify-rs/releases/)
[![GitHub issues](https://img.shields.io/github/issues/keltia/ipify-rs.svg)](https://github.com/keltia/ipify-rs/issues)
[![SemVer](https://img.shields.io/badge/semver-2.0.0-blue)](https://semver.org/spec/v2.0.0.html)
[![License](https://img.shields.io/crates/l/mit)](https://opensource.org/licenses/MIT)
[![dependency status](https://deps.rs/repo/github/keltia/ipify-rs/status.svg)](https://deps.rs/repo/github/keltia/ipify-rs)

Licensed under the [MIT](LICENSE).

1. [About](#about)
2. [API Usage](#api-usage)
3. [Installation](#installation)
4. [Example](#example)
5. [Documentation](#documentation)
6. [Contributing](#contributing)

## About

This is my attempt at writing an API & CLI client for the IPIFY API (aka ipify.org). After looking at all the other
crates, they are all flawed in some way (only IPv4, not really cargo compliant, etc.).

**Supported Platforms**

* Unix (tested on FreeBSD, Linux and macOS)
* Windows
    * cmd.exe
    * Powershell

## API Usage

**BREAKING CHANGE**: In v0.7 and later, `call()` and `call_async()` returns a `Result<String>` now.

You first create an instance of `Ipify` with `new()` set the result you want (IPv4, IPv6) and its format (plain text,
json). Result is a string inside a `Result`.

```rust
fn main() {
    use ipify_rs::{Ipify, Op};

    let ip = Ipify::new().set(Op::IPv4).call().unwrap();

    println!("My IP is {}", ip);
}
```

The four operations are specified as below:

- `OP::IPv4`
- `OP::IPv6`   (the default)
- `OP::IPv4J`  (json output)
- `Op::IPv6J`  (json output)

### Minimalistic API

If you only care about the default (plain text, IPv6 query) and don't want to reuse anything later, then `myip()` is
what you want:

```rust
use ipify_rs::myip;

fn main() {
    println!("{}", myip());
}
```

### CLI utility

There is a CLI utility bundled with the API called `ipify-cli`.

```text
    ipify-cli 0.5.0
    
    Ollivier Robert <roberto@keltia.net>
    
    Rust CLI for IPIFY API.
    
    USAGE:
        ipify-cli.exe [OPTIONS]
    
    OPTIONS:
        -4, --ipv4       Force getting IPv4
        -6, --ipv6       Force getting IPv6
        -h, --help       Print help information
        -J, --json       Request JSON output
        -q, --quiet      Quiet mode
        -V, --version    Display version and exit
```

You can see both API & CLI versions:

```
    $ ipify-cli -V
CLI ipify-cli/0.5.0 using API ipify-rs/0.7.0

```

## Examples

The file `showall.rs` inside `examples` show almost all parameters for the API. You can run it with:

```text
    $ cargo run --example showall
    ...   
    INFO - Start
    INFO - Using default, minimal API
    IP=aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh
    INFO - Using defaults (ipv6)
    IP=aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh
    INFO - Using defaults, get json
    IP={"ip":"aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh"}
    IP4="A.B.C.D"
    IP6="aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh"
```

There is an "async" example as well.

## crates.io

You can use this package in your project by adding the following
to your `Cargo.toml`:

``` toml
[dependencies]
ipify-rs = "0.7.0"
```

then you can use it in your own crates.

## Documentation

Full description of the API with examples is on [docs.rs] as usual: [Ipify].

[docs.rs]: https://docs.rs/

[Ipify]: https://docs.rs/ipify-rs

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for some simple rules.

I am now using [Jujutsu] as my VCS. You can do the same or use Git Flow as before.

I use Git Flow for this package so please use something similar or the usual github workflow.

1. Fork it ( https://github.com/keltia/ipify-rs/fork )
2. Checkout the develop branch (`git checkout develop`)
3. Create your feature branch (`git checkout -b my-new-feature`)
4. Commit your changes (`git commit -am 'Add some feature'`)
5. Push to the branch (`git push origin my-new-feature`)
6. Create a new Pull Request

[Jujutsu]: https://jj-vcs.github.io/