From 9afbb834afc769eb0e728736621930bd60bea202 Mon Sep 17 00:00:00 2001 From: Martin Algesten Date: Sun, 20 Oct 2019 19:32:18 +0200 Subject: [PATCH] Correctness doc comment --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 0223df9..ca4ddda 100644 --- a/README.md +++ b/README.md @@ -47,12 +47,28 @@ You can control them when including `ureq` as a dependency. * Minimal dependency tree * Obvious API + * Convencience over correctness This library tries to provide a convenient request library with a minimal dependency tree and an obvious API. It is inspired by libraries like [superagent](http://visionmedia.github.io/superagent/) and [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). +This library does not try to enforce web standards correctness. It uses HTTP/1.1, +but whether the request is _perfect_ HTTP/1.1 compatible is up to the user of the +library. For example: + +```rust + let resp = ureq::post("https://myapi.acme.com/blah") + .set("Jättegött", "Vegankörv") + .call(); +``` + +The header name and value would be encoded in utf-8 and sent, but that is actually not +correct according to spec cause an HTTP header name should be ascii. The absolutely +correct way would be to have `.set(header, value)` return a `Result`. This library opts +for convenience over correctness, so the decision is left to the user. + ### Sync (for now) This library uses blocking socket reads and writes, for now.