# Rincon Client

[![Crates.io][crates_badge]][crate]
[![Docs.rs][docs_badge]][documentation]
[![Apache-2.0][license_badge]][Apache-2.0]
[![Join the chat][gitter_badge]][chat]

[crates_badge]: https://img.shields.io/crates/v/rincon_client.svg
[docs_badge]: https://docs.rs/rincon_client/badge.svg
[license_badge]: https://img.shields.io/badge/license-Apache%2D%2D2%2E0-blue.svg
[gitter_badge]: https://badges.gitter.im/innoave/rincon.svg

[crate]: https://crates.io/crates/rincon_client
[documentation]: https://docs.rs/rincon_client
[Apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0
[chat]: https://gitter.im/innoave/rincon
[Rincon project]: https://github.com/innoave/rincon
[license]: ../LICENSE
[rincon]: ../rincon
[rincon_core]: ../rincon_core
[rincon_connector]: ../rincon_connector
[rincon_client]: ../rincon_client

**Type safe interaction with the ArangoDB REST API**

The [rincon_client] [crate] provides types and functions to interact with the REST API of the
[ArangoDB] server.

In [rincon_client] the REST methods are represented by structs. A method is instantiated with the 
desired parameters and data to get a method call. The method call is executed against an [ArangoDB] 
server on a connection provided by a connector. This concept allows applications to queue, 
distribute or batch process method calls.

For example, inserting a new document into an existing collection looks like:

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
struct Customer {
    name: String,
    age: u8,
}

let customer = Customer {
    name: "Jane Doe".to_owned(),
    age: 42,
};

// create a new document with the customer struct as content
let new_document = NewDocument::from_content(customer);

// create the method call to insert new_document into the 'customers' collection.
let method = InsertDocument::new("customers", new_document);

// execute the method call
let document = core.run(connection.execute(method)).unwrap();
```

The REST API of [ArangoDB] comprises a lot of methods. An overview of the currently implemented
methods can be found [here](../docs/arangodb_rest_api_methods.md).

The [rincon_client] [crate] is part of the [Rincon ArangoDB Rust driver project][Rincon project].

## Usage

### Crate Features

The [rincon_client] [crate] can be compiled with optional features to adapt to the configuration
of the [ArangoDB] server to be used. These optional features support attributes on the method calls
and their results that are specific to the related [ArangoDB] configuration.

The provided crate features are:

* `mmfiles` : support for MMFiles storage engine specific attributes (optional)
* `rocksdb` : support for RocksDB storage engine specific attributes (optional)
* `cluster` : support for cluster specific attributes (optional)
* `enterprise` : support for [ArangoDB] enterprise specific attributes (optional)

Note1: A deployed [ArangoDB] server uses either MMFiles or RocksDB storage
       engine. Therefore only one of the features `mmfiles` and `rocksdb`
       features may be activated, but not both.
         
Note2: If [rincon_client] is compiled with the `cluster` feature some API
       methods which return cluster specific fields do not work with an
       [ArangoDB] server that is not configured in a cluster. This is due to
       the [ArangoDB] server does not return cluster specific fields in a 
       single server configuration.
       
It is not necessary to activate any of the optional crate features if an
application does not need to access the feature related attributes.

### Examples

**Using MMFiles storage engine**

If you want to make use of the MMFiles related attributes and the [ArangoDB]
server is configured to use the MMFiles storage engine, [rincon_client] can be
compiled with the `mmfiles` feature to support MMFiles specific attributes
and fields within the API methods.

```toml
[dependencies]
rincon_client = { version = "0.1", features = ["mmfiles"] }
```

**Using RocksDB storage engine**

If the [ArangoDB] server is configured to use the RocksDB storage engine,
[rincon_client] can be compiled with the `rocksdb` feature to support
RocksDB specific attributes and fields within the API methods.

```toml
[dependencies]
rincon_client = { version = "0.1", features = ["rocksdb"] }
```

**Using an [ArangoDB] Cluster**

To use the [ArangoDB] cluster specific features of the API, [rincon_client]
must be compiled with the `cluster` feature enabled.

```toml
[dependencies]
rincon_client = { version = "0.1", features = ["cluster"] }
```

**Using [ArangoDB] Enterprise features**

To add support for [ArangoDB] enterprise features in the client API add this to
your dependencies:

```toml
[dependencies]
rincon_client = { version = "0.1", features = ["enterprise"] }
```

**Using an [ArangoDB] Cluster with Enterprise features**

The optional features may be combined, but only one storage engine feature may
be enabled at a time.

To use enterprise, cluster and MMFiles specific features add this to your
dependencies:

```toml
[dependencies]
rincon_client = { version = "0.1", features = ["mmfiles", "enterprise", "cluster"] }
```

To use enterprise, cluster and RocksDB specific features add this to your
dependencies:

```toml
[dependencies]
rincon_client = { version = "0.1", features = ["rocksdb", "enterprise", "cluster"] }
```

### Connector and core types

In any case we also need a connector like one provided by the [rincon_connector] crate and some
types defined in the [rincon_core] crate. This means we need to add additional dependencies:

```toml
[dependencies]
rincon_core = "0.1"
rincon_connector = "0.1"
# plus dependency as explained above
rincon_client = "0.1" 
```

## License

Licensed under Apache License, Version 2.0<br/>
see [LICENSE] or http://www.apache.org/licenses/LICENSE-2.0 for details.

### 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
licensed as above, without any additional terms or conditions.


[ArangoDB]: https://www.arangodb.com
[AQL]: https://docs.arangodb.com/3.2/AQL/index.html
[Rust]: https://www.rust-lang.org