DOCSEARCHbyAlgolia
Submit Docs

google-apis-rs

repository·main·Indexed 22 days ago

https://github.com/byron/google-apis-rs

A collection of Rust crates providing idiomatic, high-performance, and safe implementations of Google APIs generated from Google's Discovery Service. The project includes shared functionality via google-apis-common for handling resumable uploads, multipart/related uploads, and request control via the Delegate trait. It also provides google-clis-common for CLI utilities such as JSON manipulation with FieldCursor and OAuth2 application secret management. Note: This project is currently in Maintenance Mode.

Tokens
4.3K
Snippets
17
Records
22
Agent score
72%

What's inside google-apis-rs

  1. Overview of google-apis-rs

    main

    google-apis-rs is a collection of Rust crates that provide idiomatic implementations of Google APIs based on the Google Discovery Service. Each API is contained within its own crate, which can be used as a standard Rust dependency.

    Key Features:

    • Idiomatic Rust implementations.
    • First-class documentation with cross-links and code examples.
    • Support for all features, including downloads and resumable uploads.
    • Built-in safety and resilience (e.g., support for retries on transient network failures).

    Note: This project is in Maintenance Mode. No new features are being implemented, but minimal updates for security, dependencies, and API definitions are provided periodically. For an alternative implementation, consider the all-rust-org crates.

  2. Update API schemas and JSON files

    main

    The list of available APIs is cached in a dependency file. To force a full update and retrieve new API schemas from the Google Discovery API, you must clear the cache and run the update command.

    To update all JSON files and retrieve new schemas using 8 parallel downloads:

    rm -f .api.deps .cli.deps && FETCH_APIS=1 make update-json -j8

    After updating, you should run make cargo-api ARGS=check. If any APIs fail the check, they should be added to the forbidden APIs list in etc/api/shared.yaml before regenerating.

    # -j8 will allow 8 parallel schema downloads
rm -f .api.deps .cli.deps && FETCH_APIS=1 make update-json -j8

  3. Publish APIs and CLIs to Cargo

    main

    To publish the latest versions of the APIs and CLI tools to crates.io, use the following workflow:

    1. Publish artifacts: Use the -k flag to ensure the process continues even if some uploads fail (useful for retrying spurious failures).
      make publish-api publish-cli -k
    2. Commit marker files: The publish process creates marker files to prevent duplicate publishes. These must be committed to the repository.
      git add .
git commit -m "chore(cargo): publish latest version to crates.io"
git push origin main
    # Attempt to publish both API and CLI crates, continuing on error
make publish-api publish-cli -k

  4. Use Make to manage the build process

    main

    The project uses a Makefile to automate tasks. Running make without arguments will display a list of all available targets.

    Common Make Targets

    | Target | Description | | :--- | : | | help-api | Show all API targets to build individually | | help-cli | Show all CLI targets to build individually | | docs-all | Generate the full documentation index using cargo-doc | | docs-all-clean | Remove all generated documentation | | regen-apis | Clear and regenerate all generated APIs | | update-json | Rediscover API schema JSON files and update api-list.yaml | | deps | Generate a file describing how to build libraries and programs | | help | Print the help menu |

    Building Documentation and Running Tests

    • Build full documentation index: make docs-all
    • Build individual API documentation: make <api-name>-doc
    • Run doctests on all APIs: make cargo-api ARGS=test
    • Run doctests on a specific API: make <api-name>-cargo ARGS=test
    • Build CLI targets: Use the -cli suffix instead of -api (e.g., make <api-name>-cli).
    # Example: List all available API targets
make help-api

# Example: Run tests for all APIs
make cargo-api ARGS=test

  5. Prerequisites for building google-apis-rs

    main

    If you intend to generate the APIs yourself from the source, you must have the following installed:

    • make: Used to automate the build process.
    • python 3.8: Required for the mako template engine. Note that Python 3.9+ is not supported due to breaking changes in dependencies.
    • wget and an internet connection: make uses wget to automatically download necessary prerequisites into hidden directories within the repository.
    • Rust Stable (1.6 or greater): The project compiles on stable Rust. It is recommended to use rustup to manage the toolchain.

  8. Configure Application Secrets

    main

    The CLI includes a default application secret, but heavy global usage may deplete daily quotas. To use your own credentials from the Google Developer Console:

    1. Go to the Google Developer Console.
    2. Enable the required API for your project.
    3. Navigate to APIs & auth -> Credentials and download the JSON secret file.
    4. Place the file at: ${CONFIG_DIR}/${application_secret_path(util.program_name())}.

  9. Authenticate with Google APIs via the CLI

    main

    Most APIs require authentication. The CLI manages permissions via OAuth scopes.

    • Automatic Scope Selection: If you do not specify a scope, the CLI automatically selects the smallest feasible scope (e.g., read-only for read-only methods).
    • Manual Scope Selection: Use the --${SCOPE_FLAG} flag to specify a specific scope directly.
    • Token Management: Once authenticated, tokens are stored as JSON files in the configuration directory (e.g., ${CONFIG_DIR}/${util.program_name()}-token-<scope-hash>.json). No manual management is required.
    • First-time Use: The CLI will prompt you for permission the first time a scope is used.
    # Example of specifying a scope manually
${util.program_name()} --${SCOPE_FLAG} <scope_url> <resource> <method>

  11. Use MultiPartReader for multipart/related uploads

    main

    The MultiPartReader provides a Read interface that converts multiple parts into the multipart/related MIME format (RFC 2387) used by Google APIs for certain upload types.

    Use add_part to queue parts. Each part requires a reader, the size in bytes (for Content-Length), and a Mime type.

    let mut reader = MultiPartReader::default();
reader.add_part(&mut part_one_reader, size_one, mime_one);
reader.add_part(&mut part_two_reader, size_two, mime_two);
// The resulting reader can be passed to an API method expecting a body

  12. Implement a custom Delegate for request control

    main

    The Delegate trait allows you to observe and control the execution of API requests. You can implement it to handle retries, manage authentication (API keys or tokens), monitor resumable uploads, or log request progress.

    Key methods to override:

    • http_error: Decide whether to retry after a network-level error. Return Retry::After(Duration) to retry or Retry::Abort to stop.
    • http_failure: Decide whether to retry after a non-success HTTP status code.
    • token: Provide a custom OAuth token if the default authenticator fails.
    • api_key: Provide an API key if required.
    • chunk_size: Specify the size of chunks for resumable uploads (must be a power of two, minimum 1 << 18).
    • store_upload_url / upload_url: Manage state for resuming interrupted resumable uploads.
    impl Delegate for MyCustomDelegate {
    fn http_error(&mut self, _err: &hyper_util::client::legacy::Error) -> Retry {
        // Implement exponential backoff logic here
        Retry::After(std::time::Duration::from_secs(2))
    }

    fn chunk_size(&mut self) -> u64 {
        1 << 23 // 8MB chunks
    }
}