diff options
author | Ferris Tseng <ferristseng@fastmail.fm> | 2017-12-03 16:32:03 -0500 |
---|---|---|
committer | Ferris Tseng <ferristseng@fastmail.fm> | 2017-12-03 16:32:03 -0500 |
commit | bf53ecbf41d7c93f417f8f11c2affdda234e15b7 (patch) | |
tree | 56241358ec655870d639ced25801d4afe99cc5f0 | |
parent | 96a3854ece8f61d71c440498745b7b0054757753 (diff) |
finish up adding documentation
-rw-r--r-- | README.md | 66 | ||||
-rw-r--r-- | README.tpl | 20 | ||||
-rw-r--r-- | ipfs-api/src/lib.rs | 67 | ||||
-rw-r--r-- | ipfs-api/src/response/mod.rs | 2 |
4 files changed, 143 insertions, 12 deletions
@@ -1,23 +1,65 @@ -## Rust IPFS API Library +# ipfs-api + +[![Travis](https://img.shields.io/travis/ferristseng/rust-ipfs-api.svg)](https://travis-ci.org/ferristseng/rust-ipfs-api) +[![Crates.io](https://img.shields.io/crates/v/ipfs-api.svg)](https://crates.io/crates/ipfs-api) +[![Docs.rs](https://docs.rs/ipfs-api/badge.svg)](https://docs.rs/ipfs-api/) + +Rust library for connecting to the IPFS HTTP API using tokio. + +### Usage ```toml [dependencies] -ipfs-api = "0.4.0" +ipfs-api = "0.4.0-alpha" ``` -### Goals +### Examples + +Write a file to IPFS: - * Provide a full implementation of the HTTP API specification described here: https://ipfs.io/docs/api/. - * Write idiomatic rust, and make use of rust's memory safety features. - * Provide support for `go-ipfs 0.4.*`, with possible backwards compatibility features. - * Feature parity with the `go-ipfs` cli. - * Provide cross platform support for Linux, OSX, and Windows. +```rust +# +use ipfs_api::IpfsClient; +use std::io::Cursor; +use tokio_core::reactor::Core; + +let mut core = Core::new().unwrap(); +let client = IpfsClient::default(&core.handle()); +let data = Cursor::new("Hello World!"); + +let req = client.add(data); +let res = core.run(req).unwrap(); + +println!("{}", res.hash); +``` -#### Maybe (?) +Read a file from IPFS: - * Add integration tests for the `go-ipfs` implementation, and `js-ipfs` implementation of the ipfs spec. - * Explore a higher level API for interacting with IPFS. - * File system abstraction +```rust +# +use futures::stream::Stream; +use ipfs_api::IpfsClient; +use std::io::{self, Write}; +use tokio_core::reactor::Core; + +let mut core = Core::new().unwrap(); +let client = IpfsClient::default(&core.handle()); + +let req = client.get("/test/file.json").concat2(); +let res = core.run(req).unwrap(); +let out = io::stdout(); +let mut out = out.lock(); + +out.write_all(&res).unwrap(); +``` +There are also a bunch of examples included in the project, which +I used for testing + +You can run any of the examples with cargo: + +```sh +$ cargo run -p ipfs-api --example add_file +``` ## License diff --git a/README.tpl b/README.tpl new file mode 100644 index 0000000..7242565 --- /dev/null +++ b/README.tpl @@ -0,0 +1,20 @@ +# {{crate}} + +[![Travis](https://img.shields.io/travis/ferristseng/rust-ipfs-api.svg)](https://travis-ci.org/ferristseng/rust-ipfs-api) +[![Crates.io](https://img.shields.io/crates/v/ipfs-api.svg)](https://crates.io/crates/ipfs-api) +[![Docs.rs](https://docs.rs/ipfs-api/badge.svg)](https://docs.rs/ipfs-api/) + +{{readme}} + +## License + +Licensed under either of + + * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) + * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. diff --git a/ipfs-api/src/lib.rs b/ipfs-api/src/lib.rs index e2770ac..78d0569 100644 --- a/ipfs-api/src/lib.rs +++ b/ipfs-api/src/lib.rs @@ -6,6 +6,73 @@ // copied, modified, or distributed except according to those terms. // +//! Rust library for connecting to the IPFS HTTP API using tokio. +//! +//! ## Usage +//! +//! ```toml +//! [dependencies] +//! ipfs-api = "0.4.0-alpha" +//! ``` +//! +//! ## Examples +//! +//! Write a file to IPFS: +//! +//! ```no_run +//! # extern crate ipfs_api; +//! # extern crate tokio_core; +//! # +//! use ipfs_api::IpfsClient; +//! use std::io::Cursor; +//! use tokio_core::reactor::Core; +//! +//! # fn main() { +//! let mut core = Core::new().unwrap(); +//! let client = IpfsClient::default(&core.handle()); +//! let data = Cursor::new("Hello World!"); +//! +//! let req = client.add(data); +//! let res = core.run(req).unwrap(); +//! +//! println!("{}", res.hash); +//! # } +//! ``` +//! +//! Read a file from IPFS: +//! +//! ```no_run +//! # extern crate futures; +//! # extern crate ipfs_api; +//! # extern crate tokio_core; +//! # +//! use futures::stream::Stream; +//! use ipfs_api::IpfsClient; +//! use std::io::{self, Write}; +//! use tokio_core::reactor::Core; +//! +//! # fn main() { +//! let mut core = Core::new().unwrap(); +//! let client = IpfsClient::default(&core.handle()); +//! +//! let req = client.get("/test/file.json").concat2(); +//! let res = core.run(req).unwrap(); +//! let out = io::stdout(); +//! let mut out = out.lock(); +//! +//! out.write_all(&res).unwrap(); +//! # } +//! ``` +//! +//! There are also a bunch of examples included in the project, which +//! I used for testing +//! +//! You can run any of the examples with cargo: +//! +//! ```sh +//! $ cargo run -p ipfs-api --example add_file +//! ``` + extern crate bytes; #[macro_use] extern crate error_chain; diff --git a/ipfs-api/src/response/mod.rs b/ipfs-api/src/response/mod.rs index 2f3872f..e42c067 100644 --- a/ipfs-api/src/response/mod.rs +++ b/ipfs-api/src/response/mod.rs @@ -6,6 +6,8 @@ // copied, modified, or distributed except according to those terms. // +//! This module contains structures returned by the IPFS API. + pub use self::add::*; pub use self::bitswap::*; pub use self::block::*; |