I've been learning Rust over the past month and have put together two crates that are mostly interwoven. The first is
rustify which is a crate for wrapping HTTP API endpoints to enable easily querying them and deserializing responses. It contains a macro that allows easily scaffolding common REST-style endpoints. It's primarily targeting
async but also offers blocking versions of its clients.
The second is
vaultrs which leans heavily on
rustify to create a client library for Hashicorp Vault. It currently supports the PKI and secrets backend as well as wrapping responses.
I'd love feedback on the code and overall design of the crates. I spent a lot of time trying to structure them to be consistent and easily extendable. Things should be well documented as well.
cool projects A couple of things I notice:
The installation instructions in your README use
cargo add. That command requires
cargo-edit to be installed, not everybody has that, in which case you'll get a
no such subcommand error message which might confuse users.
The code block in the Advanced Usage section in rustify's README is quite long, with the explanation below it. I guess I'd find it easier to follow if code and text were more interwoven.
Ad Rustify API design:
if a trait is essential to your crate I'd personally put it in the root namespace instead of a submodule that only contains that trait, so e.g.
rustify::Endpoint instead of
the name of the
result parameter in the
endpoint macro might be a bit confusing, since it makes you think of
You might want to make the examples in your crate documentation tested, so you can't accidentally break them in future updates.
You don't need to prefix your description in
A Rust crate which ... that's implied. e.g.
A library which might be more descriptive (since there are also non-library crates).
I like to add at least one-line descriptions to the modules using module-level documentation, so that you can easily get an overview of what the modules are about.
I think for Rustify a Cargo example would be neat (e.g.
examples/foo.rs can be run with
cargo run --example=foo).
You got some broken links in your documentation.
Thanks for the great feedback! I've went ahead and implemented most of your recommendations and it looks a lot better
This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.