serde_urlencoded

serde_urlencoded is a small, focused Rust crate that bridges the application/x-www-form-urlencoded wire format with Serde’s serialization framework. It lets any type implementing Serialize/Deserialize be converted to and from URL query-string or form-body encoding without hand-written parsing logic.

Built on top of form_urlencoded for percent-decoding and rust-url conventions, it is a common dependency behind HTTP client and server crates that need to encode query parameters or decode submitted form data, including reqwest and various web frameworks.

What You Get

• to_string for serializing any Serde-compatible type into a URL-encoded string
• from_str, from_bytes, and from_reader for deserializing URL-encoded data back into typed Rust values
• Automatic percent-encoding/decoding via the form_urlencoded and rust-url crates
• A no_unsafe_code guarantee (#![forbid(unsafe_code)]) for a small, auditable dependency surface
• Standard Serde error types, making it composable with other Serde-based tooling

Common Use Cases

• Encoding query parameters for outgoing HTTP requests in clients like reqwest
• Decoding submitted HTML form bodies on the server side of a web framework
• Round-tripping structured data through URL-safe string representations for links or redirects
• Building typed configuration or filter objects from query-string parameters in REST APIs

Under The Hood

Architecture — The crate is split into two small modules, de (deserialization, src/de.rs) and ser (serialization, src/ser/ with mod.rs, pair.rs, part.rs, key.rs, value.rs). Deserialization wraps form_urlencoded::parse output in a Deserializer that hands pairs to Serde’s generic MapDeserializer, so any Deserialize impl — structs, HashMap, Vec<(String, String)> — works without crate-specific derive macros. Serialization mirrors this by walking a value’s Serde representation and emitting percent-encoded key=value pairs joined with &.

Tech Stack — Pure Rust, edition 2018, with a minimal dependency set: serde (>=1.0.69) for the data model, form_urlencoded and itoa/ryu (for fast integer/float-to-string formatting) for encoding primitives. No async runtime, no unsafe code (enforced via #![forbid(unsafe_code)]), and no build script — it’s a lightweight leaf dependency in the Rust web ecosystem.

Code Quality — The two test files tests/test_serialize.rs and tests/test_deserialize.rs cover round-trips for primitive types, nested structs, and collections. Source files are short (12-line lib.rs, ~325-line de.rs, ~555-line ser/mod.rs) and single-purpose. The crate has been effectively feature-complete since 2016, with only maintenance-level commits (98 total) since — activity is low but the surface area is small enough that this reflects stability rather than neglect.

API Design — The four entry points (to_string, from_str, from_bytes, from_reader) mirror the naming conventions used by serde_json and other Serde-format crates, so developers already familiar with Serde need zero ramp-up time. Doctested examples are embedded directly in the function docs, and the crate re-exports Serde’s standard Error type rather than inventing a new one, minimizing integration friction.