kintone-rs

DISCLAIMER: this OSS is my own personal work and does not have any relationship with Cybozu Inc. or any other organization which I belong to.

WARNING: This library is under development and is likely to undergo incompatible changes in the future.

A client library of Kintone REST APIs for Rust.

See examples in the examples directory.

Install

Add following line in your Cargo.toml right below [dependencies].

kintone = { git = "https://github.com/nojima/kintone-rs" }

Usage

This library provides a fluent API for interacting with Kintone REST APIs using method chaining. All API functions return request builders that can be configured with additional parameters and then sent to the Kintone server.

Basic Example

Here's a simple example that retrieves a record from a Kintone app and displays it:

use std::error::Error;
use kintone::client::{Auth, KintoneClient};

fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    // Create a client with your Kintone base URL and API token
    let base_url = "https://your-domain.cybozu.com";
    let api_token = "your-api-token";
    let client = KintoneClient::new(base_url, Auth::api_token(api_token));

    // Get a single record by ID
    let response = kintone::v1::record::get_record(123, 456)  // app_id: 123, record_id: 456
        .send(&client)?;
    
    println!("Retrieved record:");
    for (field_code, field_value) in response.record.fields() {
        println!("  '{}' = {:?}", field_code, field_value);
    }
    
    // Get multiple records with filtering
    let response = kintone::v1::record::get_records(123)
        .query("status = \"Active\"")
        .fields(&["name", "email", "status"])
        .send(&client)?;
    
    for record in response.records {
        println!("Record:");
        for (field_code, field_value) in record.fields() {
            println!("  '{}' = {:?}", field_code, field_value);
        }
    }

    Ok(())
}

APIs

The library currently supports the following Kintone REST APIs:

kintone::v1::record:
- get_record, get_records, add_record, update_record, update_assignees, update_status, get_comments, add_comment, delete_comment
kintone::v1::file:
- upload, download
kintone::v1::thread:
- add_thread_comment

Each function follows the same pattern: create a request builder, optionally configure it with additional parameters, and then call .send(&client) to execute the request.

let response = kintone::v1::record::get_records(app_id) // `get_records` returns a request builder
    .query("status = \"Active\"") // `query` is optional argument
    .fields(&["name", "email"])   // `fields` is also optional argument
    .send(&client)                // send the request to the server

With this pattern, we can add optional arguments to the our API without breaking backward compatibility.

For more detailed examples and usage patterns, check out the examples directory in this repository. Each example demonstrates how to use specific API endpoints and can be run directly to test the functionality.

Note: If you forget to call .send(&client), don't worry! The compiler will remind you with a helpful warning like:

unused `kintone::v1::space::AddThreadCommentRequest` that must be used

This happens because request builders are marked with #[must_use], so you'll quickly notice if you accidentally create a request without sending it.

More Examples

You can find examples in the ./examples directory. These examples takes some parameters from environment variables:

KINTONE_BASE_URL: Your Kintone domain URL (e.g., https://your-domain.cybozu.com)
KINTONE_API_TOKEN: Your API token for authentication
KINTONE_USERNAME: Your user name for Kintone
KINTONE_PASSWORD: Your password for Kintone

You can run examples like this: